Skip to main content

Contribute components

New components are implemented as subclasses of the repository component base classes under src/lfx/src/lfx/.

Contribute an example component to SkillFlaw​

Anyone can contribute an example component. For example, to create a new data component called DataFrame processor, follow the existing component structure and place the implementation in the appropriate component package.

  1. Create a Python file for your component, such as dataframe_processor.py.

  2. Write your component as an object of the Component class. Create a new class that inherits from Component and override the base class's methods.

    Backwards compatibility

    The lfx import path replaced the older custom component import path in the 1.7 migration, but the original input is still compatible and works the same way.


    _10
    from typing import Any, Dict, Optional
    _10
    import pandas as pd
    _10
    from lfx.custom.custom_component.component import Component
    _10
    _10
    class DataFrameProcessor(Component):
    _10
    """A component that processes pandas DataFrames with various operations."""

  3. Define class attributes to provide information about your custom component:


    _13
    from typing import Any, Dict, Optional
    _13
    import pandas as pd
    _13
    from lfx.custom.custom_component.component import Component
    _13
    _13
    class DataFrameProcessor(Component):
    _13
    """A component that processes pandas DataFrames with various operations."""
    _13
    _13
    display_name: str = "DataFrame Processor"
    _13
    description: str = "Process and transform pandas DataFrames with various operations like filtering, sorting, and aggregation."
    _13
    documentation: str = "https://docs.skillflaw.com/components-dataframe-processor"
    _13
    icon: str = "DataframeIcon"
    _13
    priority: int = 100
    _13
    name: str = "dataframe_processor"

    • display_name: A user-friendly name shown in the visual editor.
    • description: A brief description of what your component does.
    • documentation: A link to detailed documentation.
    • icon: An emoji or icon identifier for visual representation. SkillFlaw uses Lucide for icons. To assign an icon to your component, set the icon attribute to the name of a Lucide icon as a string, such as icon = "file-text". SkillFlaw renders icons from the Lucide library automatically. For more information, see Contributing bundles.
    • priority: An optional integer to control display order. Lower numbers appear first.
    • name: An optional internal identifier that defaults to class name.

  4. Define the component's interface by specifying its inputs, outputs, and the method that will process them. The method name must match the method field in your outputs list, as this is how SkillFlaw knows which method to call to generate each output.

    This example creates a minimal custom component skeleton.


    _21
    from typing import Any, Dict, Optional
    _21
    import pandas as pd
    _21
    from lfx.custom.custom_component.component import Component
    _21
    _21
    class DataFrameProcessor(Component):
    _21
    """A component that processes pandas DataFrames with various operations."""
    _21
    _21
    display_name: str = "DataFrame Processor"
    _21
    description: str = "Process and transform pandas DataFrames with various operations like filtering, sorting, and aggregation."
    _21
    documentation: str = "https://docs.skillflaw.com/components-dataframe-processor"
    _21
    icon: str = "DataframeIcon"
    _21
    priority: int = 100
    _21
    name: str = "dataframe_processor"
    _21
    _21
    # input and output lists
    _21
    inputs = []
    _21
    outputs = []
    _21
    _21
    # method
    _21
    def some_output_method(self):
    _21
    return ...

After creating the component:

  1. Save the implementation under src/lfx/src/lfx/components/ in the correct category.
  2. Export the component from that category's __init__.py.
  3. Add any new dependencies to pyproject.toml.
  4. Add or update documentation under docs/docs/Components/.
  5. Submit the change as a pull request.

Best practices for modifying components​

Keep class names and name stable​

Renaming a component's class or name can break existing flows.

Prefer these approaches:

  • change only the display name if the internal identity should remain stable
  • create a new component if the semantics truly changed
  • mark the old component as legacy when needed

Don't remove fields and outputs casually​

Removing fields or outputs can disconnect edges and alter saved flows.

Prefer to:

  • mark fields as deprecated
  • keep them in place when possible
  • document any migration path if a breaking removal is unavoidable

Preserve backward compatibility​

When a behavior change cannot stay backward compatible, create a new component instead of mutating the existing one beyond recognition.

Favor asynchronous I/O​

When interacting with files or external systems, prefer async-friendly APIs such as aiofile and anyio.Path where the surrounding implementation supports them.

Include tests​

Add tests for component behavior and output contracts. For more guidance, see Contribute component tests.

Document user impact in the PR​

In your pull request, clearly describe:

  • what changed
  • why it changed
  • the impact on existing users
  • any migration or compatibility notes

Example PR checklist​

  1. Create or update the component.
  2. Add or update tests.
  3. Preserve compatibility for fields and outputs where possible.
  4. Update the relevant docs.
  5. Explain the change clearly in the PR description.