CLI
Backlight.dev comes with a CLI for local development.
Use the CLI with your favorite IDE on your local machine. Works with Visual Studio Code, WebStorm or any other local editor.
Usage
npx backlight@latest
We recommend the use of npx and @latest in order to always run the latest version of the CLI. With this command you never need to upgrade Backlight.dev's CLI.
Use npx backlight@latest --help to have the latest options and commands details.
Commands
create
Create a new local Backlight.dev project, based on one of the templates available.
Use npx backlight@latest create --help or npm init backlight -- --help to explore all options.
serve
Renders a design system from your local file system.
Use npx backlight@latest serve --help to explore all options.
link
This command brings the power of npm/yarn/pnpm link to your design system.
It is useful when working locally on a project that depends on your design system. This way, your local project can reference the design system in its current state without needing to release it.
The idea is basically to run the link in the directory where you declared your dependency to the design system. Under the hood, we detect the package manager you use and call it to do the linking. It supports --watch too, making it a great way to improve your developer experience.
Arguments
| query | the query to your project where query has format "owner/name" |
Options
| --watch | watch mode - automatically update the linked package when the project is updated |
| --npm_dedupe | npm dedupe dependencies - recommended in some cases, like React environments, as React does not support being duplicated |
| --branch | branch (defaults to the main branch) |
| --yarn | use yarn link instead of npm |
Check "Open Link details" button in the top-right corner in Backlight.dev to find the current --branch value or to copy the entire command.
Please note that we generally comply to the package manager implementation - we really only provide it with the compiled version of your design system. Therefore if you meet inconsistencies with
link, it is very possible the behavior comes from the package manager. For example, the linked dependency will be replaced by the actual one when runningnpm install: this is a behavior ofnpmitself.
checkout
Checkouts an existing design system locally.
An intended use case is to start working locally on an existing design system in combination with the serve command, but it may be used in other situations as it also allows you to get the compiled output of your design system with the --compile parameter.
Pay attention that --branch option is not just a branch name, but depends on what type of branch it is (default, live or local) and must include the branch creator ID if present. Check "Open Link details" button in the top-right corner in Backlight.dev to find the current --branch value.
Use npx backlight@latest checkout --help to explore all options.
doc export
Available only to Pro and Enterprise users.
Exports documentation static site. The generated output is a dir with HTML files and assets which can be hosted on your own site or deployed to some static site hosting service.
npx backlight@latest doc export @my-workspace/ds-name
This command is useful in CI. Normal user login is not possible there, but there is an alternative method using the token BACKLIGHT_API_TOKEN. Define BACKLIGHT_API_TOKEN environment variable in order to give access to your workspace. The token can be found in the workspace settings in Backlight.
BACKLIGHT_API_TOKEN=abcdef npx backlight@latest doc export @my-workspace/ds-name --dir docs-build
Pro tip: default output dir name is based on the workspace name, but you can use --dir argument to change it.
Arguments
| query | the query to your project where query has format "owner/name" |
Options
| --branch | branch (defaults to the main branch) |
| --dir | directory where to export the documentation site in (defaults to the design system name) |
| --overwrite | whether to confirm overwrite over existing directory if it exists (defaults to false) |
export
DEPRECATED: Use checkout instead
Compiles a Backlight.dev project branch and copies the result to a local folder.
Similarly to checkout the branch name is not just the display name. Check checkout documentation for more details.
Use npx backlight@latest export --help to explore all options. Has --source-only option to export just the sources. This is useful if you didn't connect your project to source control and want to get your raw files locally.