TokiForge

Appearance

Troubleshooting ​

Common issues and solutions.

Installation Issues ​

Module Not Found ​

Error: Cannot find module '@tokiforge/core'

Solution:

bash
npm install @tokiforge/core
# Or reinstall all
npm install

TypeScript Errors ​

Error: Could not find a declaration file

Solution:

  • Ensure TypeScript 5.0+
  • Check tsconfig.json includes node_modules
  • Restart TypeScript server

Runtime Issues ​

Theme Not Switching ​

Problem: Theme changes but nothing updates

Solution:

  • Check CSS variables are being used
  • Verify runtime.init() was called
  • Check browser console for errors

CSS Variables Not Applied ​

Problem: CSS variables don't appear

Solution:

typescript
// Ensure runtime is initialized
runtime.init(":root", "hf");

// Check selector matches
runtime.applyTheme("dark", ".my-app", "custom");

SSR Errors ​

Problem: Errors during server-side rendering

Solution: TokiForge handles SSR automatically. If issues persist:

typescript
if (typeof window !== "undefined") {
  runtime.init();
}

Token Issues ​

Invalid Token Structure ​

Error: Invalid token value at path

Solution:

  • Ensure all tokens have value property
  • Check value types match (string/number)
  • Run tokiforge lint to validate

Reference Not Found ​

Error: Token reference not found: {color.primary}

Solution:

  • Check reference path is correct
  • Ensure referenced token exists
  • Verify token is defined before reference

Parse Errors ​

Error: Unexpected token in JSON

Solution:

  • Validate JSON syntax
  • Check for trailing commas
  • Use tokiforge lint to find issues

Build Issues ​

Browser Build Errors ​

Error: createRequire is not available in browser environment
Error: Could not resolve "module" / "fs" / "yaml"

Solution:

Do not import @tokiforge/core (full barrel) in browser apps — it includes Node-only APIs like TokenParser.

typescript
// Browser / framework apps
import { ThemeRuntime, TokenExporter } from '@tokiforge/core/runtime';
// or use a framework package:
import { ThemeProvider } from '@tokiforge/react';

// Browser-safe build/analysis helpers (no fs/yaml)
import { SSRUtils, TokenAnalytics, IOSExporter } from '@tokiforge/core/tools';

// CLI / build scripts only
import { TokenParser, CICDValidator } from '@tokiforge/core/node';

Error: Module '"@tokiforge/core/runtime"' has no exported member 'SSRUtils' (or TokenAnalytics, SemanticTokenManager, platform exporters, …)

Solution: As of v2.4.0 those helpers moved to @tokiforge/core/tools so /runtime stays under 3 KB. Update the import path; the default @tokiforge/core entry still exports everything.

Docs Site: Failed to resolve import "@tokiforge/core/runtime" ​

Run pnpm --filter @tokiforge/core build first (the docs predev/prebuild scripts do this automatically). The VitePress config aliases /runtime to the built dist and falls back to source when it is missing. Do not add a plain string alias for @tokiforge/core in Vite — it rewrites the /runtime subpath as a prefix and breaks resolution.

TypeScript Build Errors ​

Error: Property 'then' does not exist on type 'void'
Error: Property 'catch' does not exist on type 'void'

Solution:

In TokiForge v1.2.0, ThemeRuntime.init() and ThemeRuntime.applyTheme() are synchronous methods. Remove .then() and .catch() calls:

typescript
// ❌ Incorrect (v1.1.x style)
runtime.init(selector, prefix).then(() => {
  // ...
});

// ✅ Correct (v1.2.0)
runtime.init(selector, prefix);
// or with error handling
try {
  runtime.init(selector, prefix);
} catch (err) {
  console.error("Failed to initialize:", err);
}

Framework-Specific ​

React: Hook Errors ​

Error: useTheme must be used within ThemeProvider

Solution:

tsx
// Wrap app with ThemeProvider
<ThemeProvider config={config}>
  <App />
</ThemeProvider>

Vue: Composition API ​

Error: useTheme must be used within provideTheme

Solution:

vue
<script setup>
provideTheme(config);
const { tokens } = useTheme();
</script>

Vue: Package Resolution Error ​

Error: Failed to resolve entry for package "@tokiforge/vue". The package may have incorrect main/module/exports specified in its package.json

Solution: This issue was fixed in v1.2.0. If you're experiencing this:

  1. Ensure you're using the latest version:

    bash
    npm install @tokiforge/vue@^1.2.0

  2. Clear your node_modules and reinstall:

    bash
    rm -rf node_modules package-lock.json
npm install

  3. Clear npm cache if the issue persists:

    bash
    npm cache clean --force
npm install @tokiforge/vue@^1.2.0

Note: This was caused by incorrect package.json exports that didn't match the actual build output. The fix aligns exports with the built files (index.cjs for CommonJS, index.js for ESM).

Svelte: Store Errors ​

Error: Store not reactive

Solution:

svelte
<script>
const themeStore = createThemeStore(config);
// Use $ prefix for reactivity
$themeStore.theme
</script>

CLI Issues ​

Command Not Found ​

Error: TokiForge: command not found

Solution:

bash
# Install globally
npm install -g tokiforge-cli@^1.2.0

# Or use npx
npx tokiforge-cli@^1.2.0 init

Build Errors ​

Error: Build fails

Solution:

  • Check tokiforge.config.json exists
  • Verify token file path is correct
  • Run tokiforge lint to find issues

Performance Issues ​

Slow Theme Switching ​

Problem: Theme switching is slow

Solution:

  • Use CSS variables instead of JS tokens
  • Check for unnecessary re-renders
  • Minimize token file size

Large Bundle Size ​

Problem: Bundle is too large

Solution:

  • Tree-shake unused exports
  • Use framework adapter only
  • Don't import entire core if not needed

Still Having Issues? ​

  1. Check GitHub Issues
  2. Review Examples
  3. See API Reference