Install Knapsack

Before You Start

Before starting the installation process, ensure that your project conforms to the system specifications listed in the Required Prep document. This will help avoid any compatibility issues during installation.

Set Up Your Site ID

Before continuing, you’ll need to get your Site ID from our team. This ID will be used in the URL of your Knapsack workspace:

https://app.knapsack.cloud/site/{your-site-id}/latest

Pro Tip: Make sure to keep track of your Site ID, as you’ll need it throughout the setup process.

Once you have your Site ID, the next step is to install Knapsack in a directory that contains a package.json file. This could be an existing app or a brand-new project. If your folder doesn’t have a package.json, you can create one by running:

$ npm init -y

Now, to install Knapsack, run the following command:

$ npm create knapsack@latest

This will prompt you with some installation questions:

1. What is your Site ID? Enter your Site ID here.

2. What Renderers would you like to use? Choose the renderer(s) for your project. For example, React. You can add more later if needed.

Here’s an example of the installation process for React:

npm create knapsack@latest
? siteId › your-site-id
? renderers ›
Instructions:
    ↑/↓: Highlight option
    ←/→/[space]: Toggle selection
    [a,b,c]/delete: Filter choices
    enter/return: Complete answer
Filtered results for: Enter something to filter
◉  react
◯  vue
◯  html
◯  web-components
◯  twig
◯  hbs
◯  angular

Once installation is complete, you’ll notice a new Knapsack directory and Knapsack scripts added to your package.json.

1 {
2   "scripts": {
3     "build": "knapsack --config knapsack/knapsack.config.cjs build",
4     "start": "knapsack --config knapsack/knapsack.config.cjs start",
5     "serve": "NODE_ENV=production knapsack --config knapsack/knapsack.config.cjs serve",
6     "test": "knapsack --config knapsack/knapsack.config.cjs test"
7   }
8 }

Install Dependencies

Knapsack supports multiple package managers like npm, yarn, or pnpm.

Run the following command to install the required dependencies (example using npm):

$ npm install

Build Knapsack

After installing the dependencies, build Knapsack by running the build script added to your package.json:

$ npm run build

This will generate new folders inside the Knapsack directory:

data: Contains structured data files used by Knapsack.
dist: Contains generated files related to design tokens and metadata which is used for testing purposes, particularly in end-to-end or integration tests.
public: Contains static assets (images, fonts, etc.) that will be served directly.

Start Knapsack

To start Knapsack and launch the local development server, run:

$ npm run start

This will start the server, and you’ll see a URL http://localhost:3999 in the terminal output.

Pro Tip: Look for the rocketship emoji 🚀 in the terminal to find your local URL!

When you visit your local URL, you’ll be greeted with a sign-in screen. To access your workspace, follow these steps:

If you are the first user for your workspace, you’ll need to contact our team to invite you to the workspace. Once you’ve been invited, you’ll have the ability to invite other users yourself.

1. Receive the Workspace Invite

Once one of the Knapsack team members has invited you to your workspace, check your email for the invitation. Look for an email with the subject “You’ve been invited to join [workspace-name] on Knapsack.”

2. Click “Join Now”

Open the email and click the Join Now button.

3. Set Your Password

After clicking the link, you’ll be redirected to the password setup screen. Create a password that meets the following requirements:

• At least 8 characters in length

• Must include at least 3 of the following:

• Lowercase letters (a-z)

• Uppercase letters (A-Z)

• Numbers (0-9)

• Special characters (e.g., !@#$%^&*)

5. Complete Your Profile

Upon signing in, you’ll see a Profile Dialog. Fill in your Display Name and Role to help others know who you are.

6. Invite Team Members

Now that you’re signed in, you can invite other members to your workspace!

• Click the Knapsack logo in the top left.

• Go to Settings > Team Members.

• Click the Invite button in the top right to invite others.

Explore Knapsack

Once you’re signed in, feel free to explore your Knapsack workspace! Here’s what you can start with:

• Connecting Components: Add and modify components locally. Component additions can only be done locally before being pushed to production.

• Importing Design Tokens: Seamlessly work with design tokens and see live previews.

• Writing Documentation: Add or edit documentation in real-time.

Now that Knapsack is set up and running locally, you can start building, testing, and enjoying the collaborative power of your design system!

Next Up

Running Knapsack Locally

How to run Knapsack locally for development, testing, and deployment purposes.

Before You Start

Set Up Your Site ID