Usage with Vite (JavaScript)

A guide to installing and using Fidely UI with Vite and Jsx

Get started with a template

The easiest way to get started is to use our Vite + JavaScript template.
It comes preconfigured with Panda CSS, Ark UI, and Fidely UI v2 and theme support.

npx degit https://github.com/fidely-ui/vite-js-template

Manual Installation

If you prefer setting things up yourself, follow the steps below.

1. install Panda CSS

npm install -D @pandacss/dev
npx panda init --postcss

npm install @fidely-ui/react @fidely-ui/panda-preset

3. Update package.json scripts

Open your package.json file and add the prepare script:

{
  "scripts": {
+    "prepare": "panda codegen",
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

The prepare script ensures Panda CSS generates styles automatically when dependencies are installed.

4. Configure path aliases (JavaScript)

Since this is a JavaScript project, create a jsconfig.json file at the root

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "skipLibCheck": true,
    "baseUrl": ".",
    "paths": {
      "styled-system/*": ["styled-system/*"]
    }
  }
}

This allows Panda’s generated styled-system files to resolve correctly.

4.5 Configure Vite path aliases and optimizeDeps

Vite does not automatically read jsconfig.json or tsconfig.json path aliases at runtime.

You must explicitly configure aliases in vite.config.js and add the optimizeDeps.

Install Node types

Install Node types to avoid errors when importing Node built-ins like path

npm install -D @types/node

Update vite.config.js

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'node:path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      'styled-system': path.resolve(__dirname, 'styled-system'),
    },
  },
  optimizeDeps: {
    exclude: ['@fidely-ui/react'],
  },
})

Why we don’t use vite-tsconfig-paths

CSS imports are not supported. Due to a Vite limitation, CSS files (and CSS dialects) cannot be resolved with this plugin.

5. Configure Panda CSS

Update panda.config.ts

import { defineConfig } from '@pandacss/dev'
import { fidelyPreset } from '@fidely-ui/panda-preset'

export default defineConfig({
  presets: [fidelyPreset()],

  // Enable CSS reset
  preflight: true,

  // Files Panda should scan for styles
  include: [
    './src/**/*.{js,jsx,ts,tsx}',
    './components/**/*.{js,jsx,ts,tsx}',
    './node_modules/@fidely-ui/react/dist/panda.buildinfo.json',
  ],

  exclude: [],

  // Theme customization
  theme: {
    extend: {},
  },

  // Generate static CSS for all recipes
  staticCss: {
    recipes: '*',
  },

  // Output directory for generated styles
  outdir: 'styled-system',

  jsxFramework: 'react',

  // Remove Panda default 50 / 950 color steps
  plugins: [
    {
      name: 'panda-headless-colors',
      hooks: {
        'preset:resolved': ({ utils, preset, name }) => {
          if (name === '@pandacss/preset-panda') {
            return utils.omit(preset, [
              'theme.tokens.colors',
              'theme.semanticTokens.colors',
            ])
          }
          return preset
        },
      },
    },
  ],
})

After updating the config, generate the styled system:

npx panda codegen

6. Configure the entry CSS with layers

Open src/App.css and replace its contents with:

@layer reset, base, tokens, recipes, utilities;

You can safely remove unused CSS files if present and delete index.css.

7. Import global CSS in the app entry

Update src/main.tsx:

import { StrictMode } from "react"
import { createRoot } from "react-dom/client"

import "./App.css"
import App from "./App"

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

Enjoy ✨

You can now start using Fidely UI components:

import { Button } from '@fidely-ui/react'

const Demo = () => {
  return <Button>Click me</Button>
}