Code SourcesAsset Sets

Vue

Knapsack for Vue lets you develop and test components in isolation.
View as Markdown

Knapsack for Vue works by scanning your specified Vue code locations and automatically discovering reusable components, making them instantly available in your design system.

Why This Approach:

  • ⚡ Zero Manual Work - Knapsack finds and configures your components automatically
  • 🔄 Always Current - Your documentation stays in sync with code changes
  • 🎯 Intelligent - Understands different export patterns and component structures
  • 🚀 Scale Effortlessly - Handle hundreds of components without individual setup

Requirements

  • Vue 2 or Vue 3 - Both versions are supported
  • Webpack configuration - You’re responsible for setting up vue-loader and VueLoaderPlugin when using skipWebpackAlter: true

Install

$npm install @knapsack/renderer-vue

Configure

Minimal Setup The simplest configuration requires just specifying where your Vue components are located:

1// knapsack.config.js
2const { KnapsackVueRenderer } = require('@knapsack/renderer-vue');
3
4module.exports = configureKnapsack({
5  templateRenderers: [
6    new KnapsackVueRenderer({
7      codeSrcs: [{ path: './src/components/**/*.vue' }],
8    }),
9  ],
10};

Full Configuration Example Here’s a comprehensive example showing all available options:

1const { KnapsackVueRenderer } = require('@knapsack/renderer-vue');
2
3module.exports = configureKnapsack({
4  templateRenderers: [
5    new KnapsackVueRenderer({
6      // Code discovery paths
7      codeSrcs: [
8        { path: '@my-design-system/vue' },
9        { path: './src/components/**/*.vue' },
10        {
11          path: 'vuetify/lib/components/*',
12          filter: (path) => !path.includes('internal'),
13        },
14      ],
15
16      // Skip Webpack Alter
17      skipWebpackAlter: true,
18
19      // Webpack customization
20      webpackConfig: {
21        resolve: {
22          alias: {
23            '@': path.resolve(__dirname, 'src'),
24          },
25        },
26        module: {
27          rules: [
28            {
29              test: /\.module\.css$/,
30              use: ['style-loader', 'css-loader'],
31            },
32            {
33              test: /\.vue$/,
34              loader: 'vue-loader',
35            },
36          ],
37        },
38      },
39    }),
40  ],
41};

Code Sources

The codeSrcs array tells Knapsack where to find your Vue components and how to process them. The renderer will scan these paths, find Vue component exports, and make them available in the Knapsack UI for documentation and demos.

Local Components

Paths are relative to knapsack.config.js

1codeSrcs: [
2  // Specific directory
3  { path: './src/components/**/*.vue' },
4
5  // Multiple file extensions
6  { path: './src/ui/**/*.{vue,js,ts}' },
7
8  // Specific component types
9  { path: './src/components/atoms/*.vue' },
10  { path: './src/components/molecules/*.vue' },
11];
External Libraries

Ensure that any external library is included in your package dependencies

1codeSrcs: [
2  // Entire package
3  { path: 'vuetify' },
4  { path: 'primevue' },
5
6  // Package sub-paths
7  { path: '@my-org/design-system/components/*' },
8  { path: '@my-org/design-system/ui/*' },
9];
Smart Filtering

Use filters to control exactly which components are discovered:

1codeSrcs: [
2  {
3    path: './src/**/*.vue',
4    filter: (path) => {
5      // Only include components, exclude utilities and tests
6      return (
7        path.includes('/components/') &&
8        !path.includes('.test.') &&
9        !path.includes('.spec.') && // common for Vue test files
10        !path.includes('.stories.')
11      );
12    },
13  },
14  {
15    path: 'vuetify/lib/components/*',
16    filter: (path) => {
17      // Exclude non-component or internal Vuetify modules
18      const excludedPaths = [
19        'vuetify/lib/index',
20        'vuetify/lib/framework',
21        'vuetify/lib/util',
22      ];
23      return !excludedPaths.some((excluded) => path.includes(excluded));
24    },
25  },
26];

Skip Webpack Alter

When set to true, Knapsack will not modify the Webpack configuration at all. You’ll have complete control over configuring vue-loader (and any related settings) yourself. https://vue-loader.vuejs.org

1// knapsack.config.js
2const { KnapsackVueRenderer } = require('@knapsack/renderer-vue');
3
4module.exports = configureKnapsack({
5  templateRenderers: [
6    new KnapsackVueRenderer({
7      skipWebpackAlter: true,
8    }),
9  ],
10};

Webpack Configuration

The Vue renderer uses Webpack under the hood to process your components. When using skipWebpackAlter: true, you’re responsible for setting up your own webpack configuration including vue-loader, VueLoaderPlugin, and other Vue-specific requirements.

Refer to the vue-loader documentation for complete setup instructions.

Common Use Cases

You might need to configure webpack for:

  • Path aliases - Create import shortcuts like @/components/Button
  • CSS processing - Handle CSS modules, SCSS, styled-components, etc.
  • Asset handling - Process images, fonts, and other static files
  • TypeScript configuration - Set up TypeScript compilation and path mapping
  • Third-party library compatibility - Configure loaders for specific libraries
Common Examples

Here are some common webpack configurations you might need:

Path Aliases

1webpackConfig: {
2  resolve: {
3    alias: {
4      '@': path.resolve(__dirname, 'src'),
5      '@components': path.resolve(__dirname, 'src/components'),
6      '@utils': path.resolve(__dirname, 'src/utils')
7    }
8  }
9}

CSS Modules

1webpackConfig: {
2  resolve: {
3    alias: {
4      '@': path.resolve(__dirname, 'src'),
5      '@components': path.resolve(__dirname, 'src/components'),
6      '@utils': path.resolve(__dirname, 'src/utils')
7    }
8  }
9}

SCSS Support

1webpackConfig: {
2  module: {
3    rules: [
4      {
5        test: /\\.scss$/,
6        use: ['style-loader', 'css-loader', 'sass-loader'],
7      },
8    ];
9  }
10}

Asset Handling

1webpackConfig: {
2  module: {
3    rules: [
4      {
5        test: /\\.(png|jpg|gif|svg)$/,
6        type: 'asset/resource',
7      },
8      {
9        test: /\\.(woff|woff2|eot|ttf|otf)$/,
10        type: 'asset/resource',
11      },
12    ];
13  }
14}

TypeScript Path Mapping

1webpackConfig: {
2  resolve: {
3    alias: {
4      // Map tsconfig paths
5      '@/*': path.resolve(__dirname, 'src/*'),
6      '@components/*': path.resolve(__dirname, 'src/components/*')
7    }
8  }
9}