@webflow/webflow-cli 1.12.0 → 1.12.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @webflow/webflow-cli
 
+## 1.12.2
+
+### Patch Changes
+
+- 51547bc: Fix library bundling error with code component declaration file name starting with a number
+
+## 1.12.1
+
+### Patch Changes
+
+- dbf223b: Support function-based and array bundle config overrides for environment-specific webpack configurations
+- b50be36: Streamlined `library bundle` command for faster execution and added `--skip-update-check` global option to skip checking for `@webflow` packages updates.
+- Updated dependencies [dbf223b]
+  - @webflow/data-types@1.2.1
+
 ## 1.12.0
 
 ### Minor Changes

package/README.md

@@ -1,4 +1,4 @@
-# Webflow CLI
+# @webflow/webflow-cli
 
 The Webflow CLI is a command-line interface that allows you to interact with various Webflow developer products, including Devlink and Designer Extensions.
 
@@ -10,16 +10,285 @@ You can install the Webflow CLI globally on your machine using npm:
 npm i @webflow/webflow-cli -g
 ```
 
-# Usage
+## Usage
 
+- [Code Components Libraries](#code-components-libraries)
 - [Webflow Designer APIs & Extensions](#webflow-designer-apis-and-extensions)
 - [Devlink](#devlink)
 
-## Webflow Designer Extensions and APIs
+### Global Options
+
+The following options are available for all commands:
+
+- **`--no-input`** - Avoid prompting or doing anything interactive. Use this for CI/CD pipelines.
+- **`--manifest <path>`** - Path to a manifest .json file or directory containing webflow.json. Default: `./webflow.json`
+- **`--skip-update-check`** - Skip checking for `@webflow` packages updates
+
+### Code Components Libraries
+
+[Code Components](https://developers.webflow.com/code-components/introduction) allow you to build custom React components and share them to your Webflow workspace. The Webflow CLI provides commands to manage and share your component libraries.
+
+#### Prerequisites
+
+Before using the library commands, you need to create a `webflow.json` configuration file in your project root. Here's an example:
+
+```json
+{
+  "library": {
+    "name": "My Component Library",
+    "description": "A collection of custom components",
+    "components": ["src/components/**/*.webflow.tsx"]
+  }
+}
+```
+
+**Configuration Options:**
+
+- **`name`** (required): The display name of your library
+- **`description`** (optional): A description of your library
+- **`components`** (required): Glob pattern(s) for your component files
+- **`id`** (optional): Library ID (auto-generated on first share)
+- **`renderer`** (optional): Custom renderer configuration
+  - Can be a string path to a renderer module
+  - Or an object with `client` and `server` paths
+- **`bundleConfig`** (optional): Path to a webpack configuration file for custom bundle overrides
+
+#### Sharing a Library
+
+Share your component library to your Webflow workspace:
+
+```shell
+webflow library share
+```
+
+This command will:
+
+1. Collect metadata from your component files
+2. Bundle your components for both client and server environments
+3. Upload the bundles to Webflow's CDN
+4. Register the library in your workspace
+
+##### Authentication
+
+You need a Workspace API token to share libraries. On your first share, the CLI will guide you through an OAuth flow to authenticate and generate a token.
+
+Alternatively, you can provide a token manually with an environment variable:
+
+```shell
+export WEBFLOW_WORKSPACE_API_TOKEN=your_token_here
+webflow library share
+```
+
+You can generate a Workspace API token in your Webflow workspace settings.
+
+##### Options
+
+- **`--api-token <token>`** - Workspace API token (overrides environment variable)
+- **`--force`** - Force compilation even with warnings or type errors
+- **`--debug-bundler`** - Display final bundler configurations for debugging
+- **`--dev`** - Bundle in development mode for debugging
+- **`--verbose`** - Display more detailed information
+
+#### Bundling for Local Development
+
+Bundle your library locally without sharing to Webflow:
+
+```shell
+webflow library bundle --public-path /public
+```
+
+This is useful for:
+
+- Testing your components locally
+- Debugging bundle issues
+
+##### Options
+
+- **`--public-path <path>`** (required) - Public path for the bundle
+- **`--output-path <path>`** - Output directory (default: `./dist`)
+- **`--force`** - Force compilation even with warnings or type errors
+- **`--debug-bundler`** - Display final bundler configurations
+- **`--dev`** - Bundle in development mode
+- **`--verbose`** - Display more detailed information
+
+The bundled files will be written to the output directory with separate `client` and `server` subdirectories.
+
+#### Viewing Logs
+
+Display the logs directory and path to the latest log file:
+
+```shell
+webflow library log
+```
+
+This is helpful for debugging issues with the `share` or `bundle` commands.
+
+#### Customizing Bundle Configuration
+
+You can customize the webpack configuration used to bundle your components by providing a `bundleConfig` option in your `webflow.json` file. This allows you to add custom loaders, plugins, or modify the build process.
+
+##### Configuration File
+
+In your `webflow.json`, specify the path to your bundle config file:
+
+```json
+{
+  "library": {
+    "name": "My Component Library",
+    "components": ["src/components/**/*.webflow.tsx"],
+    "bundleConfig": "./webpack.webflow.js"
+  }
+}
+```
+
+##### Bundle Config Format
+
+Your bundle config file can export configurations in three ways:
+
+**1. Static Object**
+
+Export a static configuration object:
+
+```js
+// webpack.webflow.js
+module.exports = {
+  mode: "production",
+  devtool: "source-map",
+  module: {
+    rules: (currentRules) => [
+      ...currentRules,
+      { test: /\.svg$/, use: ["@svgr/webpack"] },
+    ],
+  },
+};
+```
+
+**2. Function (Environment-Specific)**
+
+Export a function that receives the environment (`Environment.Client` or `Environment.Server`) and returns a configuration:
+
+```js
+// webpack.webflow.js
+const { Environment } = require("@webflow/data-types");
+
+module.exports = (env) => ({
+  mode: env === Environment.Client ? "production" : "development",
+  devtool: env === Environment.Client ? "source-map" : false,
+  module: {
+    rules: (currentRules) => [
+      ...currentRules,
+      {
+        test: env === Environment.Client ? /\.client\.js$/ : /\.server\.js$/,
+        use: "custom-loader",
+      },
+    ],
+  },
+});
+```
+
+**3. Array (Multiple Configs)**
+
+Export an array of objects and/or functions to merge multiple configurations:
+
+```js
+// webpack.webflow.js
+const { Environment } = require("@webflow/data-types");
+const {
+  styledComponentsBundleConfig,
+} = require("@webflow/styled-components-utils");
+
+module.exports = [
+  // Include third-party config
+  styledComponentsBundleConfig,
+
+  // Add environment-specific settings
+  (env) => ({
+    mode: env === Environment.Client ? "production" : "development",
+  }),
+
+  // Add custom rules
+  {
+    module: {
+      rules: (currentRules) => [
+        ...currentRules,
+        { test: /\.svg$/, use: ["@svgr/webpack"] },
+      ],
+    },
+  },
+];
+```
+
+##### Common Use Cases
+
+**Adding a Custom Loader**
+
+```js
+module.exports = {
+  module: {
+    rules: (currentRules) => [
+      ...currentRules,
+      {
+        test: /\.scss$/,
+        use: ["style-loader", "css-loader", "sass-loader"],
+      },
+    ],
+  },
+};
+```
+
+**Modifying an Existing Loader**
+
+```js
+module.exports = {
+  module: {
+    rules: (currentRules) =>
+      currentRules.map((rule) => {
+        // Extend the CSS loader configuration
+        if (rule.test instanceof RegExp && rule.test.test("test.css")) {
+          // Modify the rule...
+          return modifiedRule;
+        }
+        return rule;
+      }),
+  },
+};
+```
+
+**Using CSS-in-JS Library Configs**
+
+```js
+const {
+  styledComponentsBundleConfig,
+} = require("@webflow/styled-components-utils");
+
+// For styled-components
+module.exports = styledComponentsBundleConfig;
+```
+
+##### Merging Behavior
+
+When multiple configs are provided (via array), they are merged with the following behavior:
+
+- **Regular properties**: Later configs override earlier ones
+- **Module rules**: Rules transformation functions are chained together in order
+- **Plugins**: Plugin arrays are concatenated
+- **ModuleFederationPlugin shared**: Shared dependency configurations are merged
+
+##### Blocked Properties
+
+For security and consistency, the following webpack properties cannot be overridden:
+
+- `entry`
+- `output`
+- `target`
+
+Attempting to override these properties will result in a warning and they will be ignored.
+
+### Webflow Designer Extensions and APIs
 
 [Designer Extensions](https://docs.developers.webflow.com/v2.0.0/docs/apps-overview) are single-page web Apps that run inside of of the Webflow Designer, and manipulate elements on the canvas through [Webflow's Designer APIs.](https://docs.developers.webflow.com/v2.0.0/reference/introduction-1). You can use the Webflow CLI to develop and package your Designer Extensions.
 
-### Creating an Extension
+#### Creating an Extension
 
 To create a new extension, use the `webflow extension init` command:
 
@@ -29,7 +298,7 @@ webflow extension init my-extension
 
 This command creates a new directory named `my-extension` with a basic scaffold for your extension. See more details about the scaffolding on the [App structure reference](https://docs.developers.webflow.com/v2.0.0/reference/app-structure).
 
-### Running your Extension Locally
+#### Running your Extension Locally
 
 Navigate to the newly created folder for your extension. You can serve your extension locally using the following command. The default port is set to 1337.
 
@@ -39,11 +308,11 @@ npm run dev
 
 This will run the `webflow extension serve` and command, allowing you test your App locally.
 
-#### Options
+##### Options
 
 - `port` - Serve your extension at a specific port on localhost: `webflow extension serve 1234`
 
-### Building and Bundling your Extension
+#### Building and Bundling your Extension
 
 If you're using the scaffolding built out from the `webflow extension init` command, you can create a build of your extension, an bundle it for publishing using the` npm run build` command:
 
@@ -53,7 +322,7 @@ npm run build
 
 This will run the `webflow extension bundle` CLI command, which will output a `bundle.zip` file in your extension’s directory. You can upload this extension to Webflow via the "Integrations" tab in your workspace settings. Note: The extension size limit is 5MB.
 
-# Devlink
+### Devlink
 
 DevLink allows you to visually design and build web components for React directly in Webflow. [Learn more in our DevLink overview,](https://webflow.com/devlink) and read the [DevLink documentation](https://docs.developers.webflow.com/docs/devlink-documentation-and-usage-guide).
 
@@ -98,6 +367,6 @@ by going to Site Settings > Integrations.
 npx webflow devlink sync
 ```
 
-# Terms of Service
+## License
 
-By using Webflow DevLink you agree to the [Webflow Labs Terms of Service](https://webflow.com/legal/labs-terms).
+MIT