Netlify Spark UI

Foundational design tokens, components, utilities, and other global assets to be shared across Netlify sites.

• Assets - logos, fonts, and more
• Components - Astro component library
• Styles - Element and component CSS
• Utils - Collection of JS utility functions

Versioning

When commmits are merged into main, a new release will be created via GitHub Action. semantic-release uses the commit messages to determine the impact of changes in the codebase. Follow the commit message format to properly version updates.

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

| Commit message | Release type | | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | fix: corrects prop types | ~~Patch~~ Fix Release | | feat: add sparkCool feature | ~~Minor~~ Feature Release | | perf: remove sparkCool featureBREAKING CHANGE: The sparkCool option has been removed due to performance reasons. | ~~Major~~ Breaking Release(Note that the BREAKING CHANGE: token must be in the footer of the commit) |

Check out conventional commits for other commit message types.

Troubleshooting

Check that npm and GitHub tokens have not expired. Both are used in the Release GitHub Action job.

Code Quality

Linting

This project uses ESLint to maintain code quality and consistency. To run the linter, use the following command:

npm run lint

Code Formatting

Prettier is used to format the code. To format the codebase, run:

npm run format

Design Tokens

Tokens provide a shared foundation of colors, typography, spacing, and more for our sites and apps. All token information is stored in the /packages/tokens directory. These aim to follow standards proposed in the Design Tokens Format Module.

Tokens are converted into CSS variables using the terrazzo tool.

Rebuild CSS token variables

When any files in this tokens directory are updated and merged into the main branch, the build-tokens-css GitHub Action is executed. This runs the build:tokens script, recreating the tokens.css file with updated CSS variables.

The tokens file can also be rebuilt manually with the following command:

npm run build:tokens

Local Testing

During development, you should create a documentation page for your component inside the /docs directory. This allows you to test and showcase all its configurations and variations in isolation. Once you’re ready to test the component inside your frontend application, you can link your local netlify-spark-ui package using npm link.

Setup Local Link

1. Create a global link in your local netlify-spark-ui directory:

   npm link

2. Link the package in your frontend project:

   In your frontend project directory, run:

   npm link @netlify/spark-ui

This will symlink your local netlify-spark-ui build into your frontend’s node_modules, allowing you to test changes without publishing a new package version.

Testing Preact Components

When working with Preact components, keep in mind that changes to linked packages don’t automatically trigger a rebuild in consuming projects. You’ll need to manually rebuild Preact components.

npm run build:vite

If you’ve rebuilt but still don’t see updates in your frontend while running npm run dev, Vite’s cache may be serving stale modules. In that case, clear the .vite cache in your frontend project:

rm -rf node_modules/.vite

Then restart your dev server:

npm run dev

Remote Testing

When you’re ready to validate your component changes in a deploy preview, you can publish an alpha release and install it in your frontend project.

⚠️ You will need to make sure you're in the Netlify organization in NPM to have the right authorization to publish.

Reach out to #internal-permissions in Slack

Steps to Publish an Alpha Release:

1. Make sure you're logged into npm locally

   npm login

2. Publish an alpha version of netlify-spark-ui:

   npm publish --tag alpha

3. Update the frontend’s package.json to use the alpha version:

   "@netlify/spark-ui": "1.0.0-alpha.0"

4. Install the updated package:

   npm install