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 to build your application, you can install the Katlux AI Reference Guide directly into your project with a single command.

This guide gives your AI assistant authoritative knowledge of every component API, data provider, design token, and preset — so it writes correct Katlux code without hallucinating.

Bash

npx @katlux/toolkit katlux-add-ref

This installs the reference guide at .agents/skills/KATLUX_AI_REFERENCE.md in your project. Re-run at any time to pull the latest version from the showcase.

Add the following snippet to your User Rules so Antigravity automatically parses the agent context on every interaction:

MARKDOWN

<RULE[AGENTS.md]>
# Agent Context and Guidelines

This file serves as the main entry point for AI agents to understand the workspace structure and guidelines. 
All AI interactions should automatically parse and adhere to the following references:

- [Antigravity Agent Rules](.agents/rules/rules.md)
- [KATLUX AI REFERENCE](.agents/skills/KATLUX_AI_REFERENCE.md)
</RULE[AGENTS.md]>

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

📖 View Developer Guide