Installation

Learn how to set up the Katlux Toolkit in your Nuxt 3 application. Choose between a basic quickstart or a complete, production-ready setup.

Create a new Nuxt 3 project using the official CLI:

Bash

npx nuxi@latest init my-katlux-app
cd my-katlux-app

Install the core Katlux package:

Bash

npm install @katlux/toolkit@alpha

TypeScript

export default defineNuxtConfig({
	modules: [
		'@katlux/toolkit'
	]
})

Use Katlux components globally in your Vue files:

Vue

<template lang="pug">
KButton(type="primary") Hello Katlux!
</template>

Install the toolkit, providers, presets, and any block collections you need:

Bash

npm install @katlux/toolkit@alpha @katlux/providers@alpha @katlux/preset-modern@alpha @katlux/block-ecommerce@alpha @katlux/block-charts@alpha

For a fully isomorphic and performant production build, configure transpilation, auto-imports mappings, and optimizer exclusions:

TypeScript

export default defineNuxtConfig({
	modules: [
		'@katlux/toolkit',
		'@katlux/preset-modern',
		// Inline module hook to map preset SCSS paths to precompiled CSS
		(_, nuxt) => {
			nuxt.hook('app:resolve', () => {
				nuxt.options.css = nuxt.options.css.map(path =>
					path.includes('@katlux/preset-modern') ? path.replace('.scss', '.css') : path
				)
			})
		}
	],
	
	// 1. Ensure packages compile correctly during SSR
	build: {
		transpile: [
			'@katlux/providers',
			'@katlux/toolkit',
			'@katlux/preset-modern'
		]
	},

	// 2. Enable auto-imports for Katlux providers
	imports: {
		global: true,
		transform: {
			include: [
				/[\\/]node_modules[\\/]@katlux[\\/]providers/
			]
		}
	},

	vite: {
		// 3. Exclude providers from Vite optimizeDeps to ensure hot-reloads
		optimizeDeps: {
			exclude: ['@katlux/providers']
		},
		
		// 4. Resolve preset style assets to compiled CSS
		resolve: {
			alias: {
				'@katlux/preset-modern/dist/runtime/assets/scss/index.scss': '@katlux/preset-modern/dist/runtime/assets/scss/index.css'
			}
		}
	},

	// 5. Configure active preset
	katluxToolkit: {
		activePreset: 'modern'
	}
})

TypeScript

export default defineAppConfig({
	katluxToolkit: {
		presetList: [
			{ name: 'Default', value: 'default' },
			{ name: 'Modern', value: 'modern' }
		],
		activePreset: 'modern'
	}
})

If you use AI coding assistants (Cursor, Antigravity, Claude, Copilot, Windsurf), Katlux provides both modular AI skill files and a high-performance Model Context Protocol (MCP) server.

The MCP server gives your assistant surgical, on-demand tool access to component APIs, exact SVG icons, design tokens, and self-correction code validation — saving 90%+ tokens per query.

Bash

npx @katlux/toolkit katlux-add-ref

Running katlux-add-ref installs the Katlux skills at .agents/skills/katlux-* and auto-configures the Katlux MCP server for Cursor, Antigravity, and VS Code automatically.

Automatically configured by katlux-add-ref. To manually register the MCP server, add to .cursor/mcp.json:

JSON

{
  "mcpServers": {
    "katlux": {
      "command": "npx",
      "args": ["-y", "@katlux/mcp"]
    }
  }
}

For advanced monorepo development, creating custom presets, or contributing to Katlux:

📖 View Developer Guide