> 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-component-dev-approach.md). # Sygnal's Code Component Dev Approach ## Goals * Rapid prototyping * Methodology for R\&D and proof-of-concept on more complex component design patterns * Maximum styling support * Leveraging the Designer UX as much as possible * Minimize the risk of production impact to users * Supporting tight CI/CD * Unit testing * Integration testing * Separate DEV, TEST, PROD environments * User-accessible TEST for community validation on new features * Separate DEV, TEST, PROD environments ### Development Approach ( v1 ) The components I'm most interested in push the design boundaries of Webflow's setup a bit, so I'm two-phasing it using two separate Code Component projects - a *prototyping lib* and a *production library*. #### Phase 1 - prototyping ( `sygnal-prototype` lib ) The prototype component is built in a separate lib specifically for prototyping. {% hint style="success" %} As a separate library, it can be deployed to any project without impacting the production lib deployments. {% endhint %} The prototype lib contains a number of features to aid development, including various "test" components that model specific solution-approaches to specific needs like slot-processing, state sharing, and attribute configurations. These can be used both as a reference for the dev team, and for any AI coding assistants like Claude code that the team might utilize. In this library; * Functional prototype tested locally using Vite, and framed in App.tsx. * If the component has shared state like Sygnal's Audio player ( playing one pauses others ), that framework can also be built and tested locally. * As a separate library, it can be deployed to any project without impacting the production lib deployments. #### Phase 2 - testing Once it's feature complete, I deploy the lib into Sygnal's main Webflow workspace as the `sygnal-prototype` lib. This keeps it discrete. Integration testing is then performed; * Designer experience testing * Component functionality on the canvas * Slot functionality * Slotted collection list processing * Property presentation and ordering * Styling concerns * Preview mode * Published site testing * Functional testing * Richtext processing * HTML/CSS review This process requires a lot of recurring deployments, but that's quite fast with the smaller prototype lib, from an SSD. #### Production Release Once fully complete, the code is manually copied over to the appropriate production library, e.g. `sygnal-layout`, `sygnal-forms`, `sygnal-maps` , etc. From here it needs to be deployed to; * Sygnal's workspace * Client workspaces * The community as a whole {% hint style="warning" %} **2025-09-23 - CLIENT WORKSPACE DEPLOYMENTS ( UNTESTED )** \ Current plan is to maintain multiple .env files to swap the API\_TOKEN with a script, and then deploy. **Ideally this would be handled with an --env or --config param on the CLI deploy command.** {% endhint %} {% hint style="danger" %} **2025-09-23 - PUBLIC DEPLOYMENTS ( UNTESTED )**\ Current plan is to make the lib public as a repo, with a detailed guide on how to git clone, install npm, and deploy to your own workspace. {% endhint %} ## Development Approach ( v2 ) {% hint style="warning" %} **UNDER DEVELOPMENT**\ The v1 approach is not particularly friendly to ongoing development processes, since it requires manually copying code from the prototype lib to the production lib. {% endhint %} To mitigate that, we're shaping a more CI/CD-friendly v2 process. * Single Code Components project * Github repo * `dev` branch, which is used for development, and pushed to a special DEV workspace for testing * PR to `main` branch, which contains the production code. Here, Git actions or other mechanics can be used to; * Automatically install the new production updates to workspaces. * Notify the user community of updates that they can selectively pull. Hypothetically, this would look something like; ``` npx webflow library share --no-input --config webflow-prod.json ``` {% hint style="info" %} **TEST WORKSPACE PROBLEM** \ According to rhe release docs {% endhint %} {% hint style="info" %} **PRO TIP**\ Consider using a separate test workspace for test deployments. This ensures that you can fully use the same full component instance and name from a DEV branch of your repo and update it anytime. {% endhint %} * API\_KEY change * ? Lib name * Ideally the ability to use a single multi-workspace API-KEY, while specifying the exact workspace ID you're deploying into ( this is Cloudflare Wrangler approach ) {% hint style="success" %} **MARKETPLACE LIBS** \ This same CI/CD mechanic would ideally inform Marketplace lib updates as well. {% endhint %} ## Future {% hint style="danger" %} As any WordPress dev knows, component marketplaces are a double-edged sword. We want to engineer a more bulletproof solution that mitigates; * Shipment of breaking changes * Users unable to revert to a working version * Malware risks * Abandoned components * Breaking platform dependencies {% endhint %} * Unified repo with free v. paid versions of a component. to support DEV, TEST, and PROD, with separate branches or feature flags ### Webflow Features Ideally the ability to use a single multi-workspace API-KEY, while specifying the exact workspace ID you're deploying into ( this is Cloudflare Wrangler approach ) Marketplace support for Code Component libs + Hybrid libs. Hybrid libs have the same name, and code components are a facet. Use cases; * Map ( CC ) + Pins ( NC ) makes * Slider ( CC ) + Slides ( NC ) Build feature flags, or runtime feature flags that support both free and paid libs, Ideally within the marketplace. You install Sygnal Maps, and you get a bunch of free stuff. If you upgrade to PRO, features, capabilities, and any usage tie-ins ( LLMs, etc ) expand. This supports; * Free trial setups * Free basic plans + Pro advanced plans * Possibly plan tiering Ideally this would be managed internally by Webflow using library-facing feature flags. Use cases; * I have a chatbot, I want; * Free plan of 10 convos / day * Paid plans starting at 100 convos / day * I have a map library; * The image map, and Google map are free * The interactive Globe is pro * I have a mutlistep form library; * The basic MSF and all basic forms components are free, limited to a 3 step process. * Pro unlocks; * Up to 100 steps * Advanced validations * Advanced forms components like range sliders ### PROD * PR to PROD * Google Action to deploy to prod? ``` npx webflow library share --no-input --config webflow-prod.json ``` {% hint style="warning" %} Also need API key control for deploying to client workspaces. {% endhint %} --- # 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-component-dev-approach.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.