Custom Components
Locofy Config File

How to Configure the Component Library

Importing from GitHub and importing using the Locofy CLI both require a locofy.config.json file at your project root.

How to structure locofy.config.json

Paths in the file must be relative to the project root.

SectionRequiredDescription
componentsYesList of components to import. Each entry is an object with at least path and name, plus optional figmaComponentName, figmaPageName (Figma page—e.g. design system—used to find a component by name on that page), and a props array. (You can still use a legacy flat list of file path strings for a minimal setup; the object form is recommended for prop mapping.)
frameworkNoe.g. "react" — helps tooling interpret your codebase.
projectIdNoLocofy project id (often added after linking the repo or CLI).
projectNameNoDisplay name for the project.
wrapperNoPath to a wrapper component when your library needs one.
webpackNoPath to a custom webpack config used for the preview build.
publicPathNoPath to static assets referenced by components.

Sample: rich component entries

Use name to match your exported component, optional figmaComponentName to tie the config to a specific Figma component name, and props for the schema Locofy uses in the plugin (optional previewValue only affects Props mapping previews there). Prop fields, Figma examples, and detection strategies are in Manual Prop Mapping. For mapFn expressions, see Complex prop mapping (mapFn).

{
  "components": [
    {
      "path": "./src/components/Button.tsx",
      "name": "Button",
      "figmaComponentName": "Button",
      "props": [
        {
          "name": "variant",
          "figmaPropName": "Variant",
          "type": "enum",
          "enum": ["primary", "ghost"],
          "valueMapping": {
            "primary": ["Primary"],
            "ghost": ["Ghost"]
          }
        },
        {
          "name": "children",
          "figmaPropName": "Label",
          "type": "string",
          "config": { "layer": [{ "name": "Label" }] }
        }
      ]
    }
  ],
  "framework": "react",
  "projectId": "your-project-id",
  "projectName": "Your Project"
}

In Figma, the component name should match figmaComponentName, and each property in the right sidebar should match figmaPropName on the corresponding prop. Step-by-step tables (Button, Listing card, Header links + mapFn) are in Manual Prop Mapping — Figma component properties and locofy.config.json.

Sample: legacy path-only list

For a quick import without inline prop metadata, you can list component files as strings (prop schemas can be filled in later via the plugin, including AI-assisted export from the plugin, or by hand):

{
  "components": [
    "./src/components/Button.tsx",
    "./src/components/Header.tsx"
  ],
  "wrapper": "./src/Wrapper.tsx",
  "webpack": "./webpack.locofy.js",
  "publicPath": "./public/assets"
}

Note: See how to create a Wrapper Component.

Structuring ComponentsImport using CLI