Vue | Knapsack Documentation

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:

// knapsack.config.js
const { KnapsackVueRenderer } = require('@knapsack/renderer-vue');
module.exports = configureKnapsack({
  templateRenderers: [
    new KnapsackVueRenderer({
      codeSrcs: [{ path: './src/components/**/*.vue' }],
    }),
  ],
});

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

const { KnapsackVueRenderer } = require('@knapsack/renderer-vue');
module.exports = configureKnapsack({
  templateRenderers: [
    new KnapsackVueRenderer({
      // Code discovery paths
      codeSrcs: [
        { path: '@my-design-system/vue' },
        { path: './src/components/**/*.vue' },
        {
          path: 'vuetify/lib/components/*',
          filter: (path) => !path.includes('internal'),
        },
      ],
      // Skip Webpack Alter
      skipWebpackAlter: true,
      // Webpack customization
      webpackConfig: {
        resolve: {
          alias: {
            '@': path.resolve(__dirname, 'src'),
          },
        },
        module: {
          rules: [
            {
              test: /\.module\.css$/,
              use: ['style-loader', 'css-loader'],
            },
            {
              test: /\.vue$/,
              loader: 'vue-loader',
            },
          ],
        },
      },
    }),
  ],
});

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

codeSrcs: [
  // Specific directory
  { path: './src/components/**/*.vue' },
  // Multiple file extensions
  { path: './src/ui/**/*.{vue,js,ts}' },
  // Specific component types
  { path: './src/components/atoms/*.vue' },
  { path: './src/components/molecules/*.vue' },
];

External Libraries

Ensure that any external library is included in your package dependencies

codeSrcs: [
  // Entire package
  { path: 'vuetify' },
  { path: 'primevue' },
  // Package sub-paths
  { path: '@my-org/design-system/components/*' },
  { path: '@my-org/design-system/ui/*' },
];

Smart Filtering

Use filters to control exactly which components are discovered:

codeSrcs: [
  {
    path: './src/**/*.vue',
    filter: (path) => {
      // Only include components, exclude utilities and tests
      return (
        path.includes('/components/') &&
        !path.includes('.test.') &&
        !path.includes('.spec.') && // common for Vue test files
        !path.includes('.stories.')
      );
    },
  },
  {
    path: 'vuetify/lib/components/*',
    filter: (path) => {
      // Exclude non-component or internal Vuetify modules
      const excludedPaths = [
        'vuetify/lib/index',
        'vuetify/lib/framework',
        'vuetify/lib/util',
      ];
      return !excludedPaths.some((excluded) => path.includes(excluded));
    },
  },
];

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

// knapsack.config.js
const { KnapsackVueRenderer } = require('@knapsack/renderer-vue');
module.exports = configureKnapsack({
  templateRenderers: [
    new KnapsackVueRenderer({
      skipWebpackAlter: true,
    }),
  ],
});

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

webpackConfig: {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@components': path.resolve(__dirname, 'src/components'),
      '@utils': path.resolve(__dirname, 'src/utils')
    }
  }
}

CSS Modules

webpackConfig: {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@components': path.resolve(__dirname, 'src/components'),
      '@utils': path.resolve(__dirname, 'src/utils')
    }
  }
}

SCSS Support

webpackConfig: {
  module: {
    rules: [
      {
        test: /\\.scss$/,
        use: ['style-loader', 'css-loader', 'sass-loader'],
      },
    ];
  }
}

Asset Handling

webpackConfig: {
  module: {
    rules: [
      {
        test: /\\.(png|jpg|gif|svg)$/,
        type: 'asset/resource',
      },
      {
        test: /\\.(woff|woff2|eot|ttf|otf)$/,
        type: 'asset/resource',
      },
    ];
  }
}

TypeScript Path Mapping

webpackConfig: {
  resolve: {
    alias: {
      // Map tsconfig paths
      '@/*': path.resolve(__dirname, 'src/*'),
      '@components/*': path.resolve(__dirname, 'src/components/*')
    }
  }
}