Sygnal's Code Components Development Framework

DOCUMENTATION IN PROGRESS. Considering renaming to WFCC.

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 ⚠️

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.

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

@sygnal/code-component adds deployment scripts and branch-conditioned deployment to your repo.

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 

Start with all feature branches merged in.

version.ts

Add src/version.ts

export const VERSION = '1.0.0'; 

Install build scripts

Install the build scripts fron NPM;

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

Start with all feature branches merged in.

Install build scripts

Install the build scripts fron NPM;

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

https://www.npmjs.com/package/@sygnal/code-component

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)

cd d:\projects\sygnal-webflow-component
npm publish

Option 2: Private Git Repository

// 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

https://www.npmjs.com/package/sygnal-webflow-componentwww.npmjs.com

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:

// 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):

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:

// sygnal-webflow-component/index.js
export function deploy(options) { /* ... */ }
export function switchConfig(branch) { /* ... */ }
export function updateVersion(version) { /* ... */ }

Usage in project:

// 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)