Configure Knapsack

Overview

The knapsack.config.cjs file provides all the necessary information for Knapsack to correctly bootstrap and manage your design system. It defines paths, settings, and options for how Knapsack operates, including the handling of design tokens, distribution directories, template renderers, plugins, and cloud settings. Properly configuring this file ensures that your Knapsack workspace functions smoothly and efficiently.

Configuration Overview

Below is an example configuration to help you understand how to set up your knapsack.config.cjs file:

1
const DesignTokensJson = join(__dirname, './packages/design-tokens/design-tokens.json');
2
const DesignTokenDist = join(__dirname, './packages/design-tokens/dist');
3
4
module.exports = configureKnapsack({
5
  designTokens: {
6
    distDir: DesignTokenDist,
7
    srcFilePath: DesignTokensJson,
8
    targets: {
9
      android: { enabled: true },
10
      css: { enabled: true },
11
      ios: { enabled: true },
12
      js: { enabled: true },
13
    },
14
  },
15
  dist: join(__dirname, './dist'),
16
  public: join(__dirname, 'ks-public/'),
17
  data: join(__dirname, './data'),
18
  version,
19
  templateRenderers: [
20
    new HTMLRenderer(),
21
    new KnapsackWebComponentRenderer(),
22
  ],
23
  plugins: [
24
    configureChangelogMd({
25
      changelogPath: './CHANGELOG.md',
26
    }),
27
  ],
28
  cloud: {
29
    siteId: 'workspace-starter',
30
    repoName: 'workspace-starter',
31
    repoOwner: 'knapsack-cloud',
32
  }
33
});

designTokens

The designTokens section configures the Knapsack Token Engine, allowing you to specify how design tokens are processed and where they are stored.

• srcFilePath: This property points to the file containing your design token data.
• distDir: Specifies the directory where the processed design tokens will be output.
• targets: This property enables or disables specific targets for generating design tokens.
  • Available targets include: android, css, ios, and js
  • You can selectively include or exclude targets based on your project needs.

To learn more about configuring the design tokens pipeline, see this document.

dist

Specifies the directory where Knapsack will output various system assets, such as the pattern manifests and type definitions.

public

Defines the directory for public assets in your workspace, typically used for serving static files.

data

Points to the directory where Knapsack stores and retrieves its internal data files, such as metadata, configurations, and documentation content.

version

This represents the current version of your Knapsack workspace, typically pulled from your package version or manually set.

templateRenderers

The templateRenderers section configures the renderers used in your Knapsack workspace. Knapsack supports several templating languages and frameworks, including React, Vue, Twig, Web Components, Angular, HTML, and Handlebars.

Each renderer has its specific configuration options, and detailed documentation is available for each renderer here.

plugins

This section allows you to configure and enable various plugins that extend Knapsack’s functionality. For example, you can configure a change log plugin to manage and display version histories within your workspace (pictured in the example configuration at the top of this document).

cloud

The cloud section contains settings related to your Knapsack cloud integration:

• siteId: The unique identifier for your Knapsack site.
• repoName: The name of the repository connected to Knapsack.
• repoOwner: The owner of the connected repository.

Note: If Knapsack is not located within the root of your repository, add the repoRoot key to the cloud section:

1
module.exports = configureKnapsack({
2
  ...
3
  cloud: {
4
    siteId: 'workspace-starter',
5
    repoName: 'workspace-starter',
6
    repoOwner: 'knapsack-cloud',
7
    repoRoot: join(__dirname, '../..'),
8
  }
9
});

devServer

The devServer configuration in Knapsack allows you to set up HTTPS for your local development environment. This is useful for testing security-related features, simulating production-like environments, and preventing browser warnings.

devServer Configuration Options

Knapsack provides a devServer object that lets you control how your local server behaves, from enabling HTTPS to customizing the port and host. Here’s a basic example:

devServer: {
  https?: boolean;
  ssl?: {
    cert: string;
    key: string;
  };
  port?: number;
  host?: string;
}

This setup lets you easily tweak the server to match your specific needs.

Enabling HTTPS for Local Development

To enable HTTPS in Knapsack, just add this to your knapsack.config.cjs:

1
devServer: {
2
  https: true,
3
}

Knapsack will automatically serve your project over HTTPS using a self-signed certificate.

Using Custom SSL Certificates

If you need to use your own SSL certificates, you can configure Knapsack to use them with the ssl option:

1
devServer: {
2
  https: true,
3
  ssl: {
4
    cert: './path-to-SSL-cert',
5
    key: './path-to-SSL-key',
6
  },
7
}

This is useful for enterprise teams or when working with certificates from a trusted authority.

Customizing Ports and Hosts

Custom Port

By default, Knapsack runs on port 3000, but if you need to use a different port, you can set it like this:

1
devServer: {
2
  port: 8080,  // Replace with your preferred port number
3
}

Custom Host

Need to set a specific host? You can do that too:

1
devServer: {
2
  host: 'localhost',  // Or your custom host
3
}

These options give you flexibility when configuring your local server to avoid conflicts or match your network needs.

Putting It All Together: A Full devServer Example

Here’s a full example that combines everything:

1
devServer: {
2
  https: true,           // Enable HTTPS
3
  ssl: {
4
    cert: './path-to-SSL-cert',  // Use custom SSL certificate
5
    key: './path-to-SSL-key'     // Use custom SSL private key
6
  },
7
  port: 8080,            // Set a custom port
8
  host: 'localhost'      // Set a custom host
9
}

With this setup, you can:

• Secure your dev server with HTTPS using either the default or custom SSL certificates.

• Customize the port and host to fit your local development environment.

Conclusion

By properly configuring the knapsack.config.cjs file, you can fully leverage Knapsack’s capabilities, ensuring that your design system is well-organized, consistent, and easy to maintain across different environments.