> For the complete documentation index, see [llms.txt](https://sygnal.gitbook.io/sygnal-webflow-components/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sygnal.gitbook.io/sygnal-webflow-components/cc/technical-notes/sygnals-code-components-development-framework.md). # Sygnal's Code Components Development Framework {% hint style="danger" %} **DOCUMENTATION IN PROGRESS.** \ Considering renaming to **WFCC**. {% endhint %} Sygnal has designed the `@sygnal/code-component` NPM package to manage your Webflow code component deployment processes. This documentation covers what it does, and how to use it. ## Why We Build This At release ( Sep-2025 ), code components present some challenges. Development, revision, & version management; * Code components do not have any intrinsic versioning mechanic, which means that there is no way to distinguish between code in development, testing, and production. Testing; * Integration testing requires you do deploy to a workspace, however your Test code library will overwrite your production library, and risks breaking production sites. * It's possible to deploy to a different workspace using key-swapping scripts, however this means paying for an additional workspace for testing purposes alone. * There's no way to visually identify that a library contains test code * There's no way to visually identify that a component contains test code Versioning; * Breaking changes can happen, but without a versioning mechanic, there is no intrinsic way to "lock" a workspace's library installation to a specific version of a library. In widespread library deployments this is important to ensure stability and hotfixing support. ## Features * Single-repo development, one per library * Easy testing through the use of feature branches * Separates DEV, TEST, and PROD environments * Avoids conflict between TEST and PROD workspaces by separating the libs. * TEST lib versions have `-test` appended to the library code. * Clearly indicates library version, for tracking and support across multiple workspace installs * e.g. `My Library v1.0.0` * Visual distinction between TEST and PROD library versions in the same workspace * e.g. `My Library v1.0.0` v. `My Library Test v1.0.0 ⚠️` * Visually distinguishes between TEST and PROD component versions in the same workspace * e.g. `My Component` v. `My Component ⚠️` {% hint style="success" %} This solution makes it easy to do local development, Webflow integration testing, and production deployments. You can TEST and deploy in the same workspace, without conflict, even within the same project. **It's also easy to identify TEST components and libraries in the Library and Components panels, in the Nav and Canvas, and in Quick find.** {% endhint %} ## Requirements * Git. Your project must be in a Git repo. This is fundamental to how feature work is safely separated. * Your main branch should be called `main` * Setup of your `package.json`, `.gitignore`, `webflow.json` according to our setup notes below ### Best Practices * Use Vite for local testing * Use `feature/*` branches for all development and refactoring work * Use `main` for integration work * Reserve `release/*` branches for marketplace deployments ( coming soon ) ## Usage Notes {% hint style="success" %} `@sygnal/code-component` adds **deployment scripts** and **branch-conditioned deployment** to your repo. {% endhint %} ### Developing a new component * Create a new feature branch, e.g. `feature/my-component` * Create your components, do you refactoring, etc. * Do local testing with `npm run dev` using Vite * Integration testing * `npm run deploy` to your workspace * Because you're deploying while not on `main` it will be update the TEST version of the library, ending in Test and with an icon for easy identification. * Merging a feature * Merge the feature branch into `main` * Deploy `main` * Discarding a feature branch * If you want to abandon a line of experimentation, simply delete that feature branch ## Using Sygnals Code Components ## New Projects Must be a Git repo ``` npm init -b main ``` {% hint style="warning" %} Start with all feature branches merged in. {% endhint %} ### version.ts Add src/version.ts ``` export const VERSION = '1.0.0'; ``` ### Install build scripts Install the build scripts fron NPM; ```bash npm install --save-dev @sygnal/code-component@latest ``` ### webflow\.json Rename `webflow.json` to `webflow.main.json` ### package.json Add deploy script; ``` "scripts": { "deploy": "sygnal-deploy", }, ``` ### .gitignore Add- ``` webflow.json /deploy ``` ## Deploy Your first deployment will require an authentication ``` npm run deploy ``` Do you very first deployment from `main` ``` npx webflow library share ``` ## Migrating Projects {% hint style="warning" %} Start with all feature branches merged in. {% endhint %} ### Install build scripts Install the build scripts fron NPM; ```bash npm install --save-dev @sygnal/code-component@latest ``` ### webflow\.json 1. If `webflow.main.json` does NOT exist, rename `webflow.json` to `webflow.main.json` 2. Delete `webflow.test.json` if it exists ### Delete old deployment scripts Delete `scripts/deploy.js` if it exists ### package.json Change deploy to `sygnal-deploy` The resulting script command will look like this; ``` "scripts": { "deploy": "sygnal-deploy", }, ``` ### .gitignore Add- ``` webflow.json /deploy ``` Setup ``` npm install ... ``` Webflow config Duplicate webflow\.json to webflow\.main.json Make edits to npm run deploy * Which branch you're on ## Migration ``` npm install --save-dev @sygnal/code-component ``` Delete script webflow\.test.json #### Next Steps to Share Across Projects When you want to use this in other projects: **Option 1: Publish to NPM** (recommended) ```bash cd d:\projects\sygnal-webflow-component npm publish ``` **Option 2: Private Git Repository** ```json // In other project's package.json "sygnal-webflow-component": "github:your-org/sygnal-webflow-component#v1.0.0" ``` **Option 3: Keep using `npm link`** (for local development) * Already set up and working! ## Implementation NPM package with executable script {% embed url="" %} ``` https://www.npmjs.com/package/@sygnal/code-component ``` ## Future Approaches * NPM package **`sygnal-webflow-component`** * Github template ### Options for Sharing the Deploy Script You have **4 main approaches**, each with tradeoffs: #### 1. **NPM Package with Executable Script** (Recommended) Package the deploy script as an executable that projects can run. **Structure:** ``` sygnal-webflow-component/ ├── bin/ │ └── deploy.js # Your deploy script ├── package.json └── README.md ``` **Usage in projects:** ```json // package.json { "scripts": { "deploy": "sygnal-deploy" }, "devDependencies": { "sygnal-webflow-component": "^1.0.0" } } ``` **Pros:** * Simple to use * No code changes needed in consuming projects * Script updates automatically when package updates **Cons:** * Each project still needs its own `webflow.main.json`, `webflow.test.json`, and `src/version.ts` files * Less flexible for customization #### 2. **NPM Package with Configuration-Based CLI** Create a more sophisticated CLI that reads config from the consuming project. **Structure:** ``` sygnal-webflow-component/ ├── bin/ │ └── cli.js ├── lib/ │ └── deploy.js ├── package.json ``` **Config in consuming project** (`sygnal.config.js`): ```js module.exports = { versionFile: 'src/version.ts', mainConfig: 'webflow.main.json', testConfig: 'webflow.test.json', // Optional overrides } ``` **Pros:** * Configurable per project * Centralized logic updates * Can add more commands (build, validate, etc.) **Cons:** * More complex to build * Requires config file in each project #### 3. **NPM Package with Programmatic API** Export functions that projects can use in their own scripts. **Package exports:** ```js // sygnal-webflow-component/index.js export function deploy(options) { /* ... */ } export function switchConfig(branch) { /* ... */ } export function updateVersion(version) { /* ... */ } ``` **Usage in project:** ```js // scripts/deploy.js const { deploy } = require('sygnal-webflow-component'); deploy({ versionFile: 'src/version.ts', mainConfig: 'webflow.main.json', testConfig: 'webflow.test.json' }); ``` **Pros:** * Maximum flexibility * Can compose with other logic * Good for unique per-project needs **Cons:** * Each project still needs its own deploy script * More boilerplate in each project #### 4. **Shared Template Repository** Not an NPM package, but a GitHub template repo. **Pros:** * Copy entire project structure * Good for fully standardized setups **Cons:** * No automatic updates * Not ideal if you want to evolve the tooling ### Recommendation **Start with Option 1 (Executable Script)**, but design it to evolve into Option 2: ``` sygnal-webflow-component/ ├── bin/ │ └── deploy.js ├── lib/ │ ├── config.js # Config loading logic │ ├── version.js # Version extraction │ └── webflow.js # Webflow commands ├── package.json └── README.md ``` This gives you: * Quick wins (script works immediately) * Room to grow (add config file support later) * Shared conventions (all projects use same patterns) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sygnal.gitbook.io/sygnal-webflow-components/cc/technical-notes/sygnals-code-components-development-framework.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.