@arviahq/vite-plugin

@arviahq/vite-plugin

Framework-agnostic Vite plugin for .arv files: CSS + JS generation with HMR, plus optional .d.ts emission. Most projects use a framework wrapper (@arviahq/vite-plugin-react, -vue, -preact) instead of this package directly.

import { arvia } from "@arviahq/vite-plugin";

export default defineConfig({
  plugins: [arvia()],
});

Options

Option	Type	Default	Description
theme	string	src/theme.arv if present	Theme file for virtual:arvia/tokens and HMR (not an ambient token scope).
dts	boolean | 'sibling' | 'central' | DtsConfig	'central'	How to emit .d.ts declarations (see below).

Virtual modules

Id	Purpose
virtual:arvia/tokens	Re-exports the theme file's tokens + named group exports.
virtual:arvia/tokens/<group>	Default-exports one token group.
virtual:arvia/css-manifest	Structured CSS manifest (see CSS output docs).

With css.importStrategy: 'manual' | 'manifest' (including libraryMode), generated .arv JS modules are marked moduleSideEffects: false so unused imports can tree-shake.

Type checking with plain tsc (dts)

By default (dts: 'central') the plugin emits real declarations so you can typecheck .arv imports with plain tsc — no arvia-tsc, no plugins entry. Declarations are mirrored into .arvia/types, e.g. src/components/stack.arv → .arvia/types/components/stack.arv.d.ts, updated on save and at build with stale mirrors pruned. The plugin drops a self-ignoring .gitignore into that folder, so you never commit generated declarations and don't touch your root .gitignore.

The one thing you add is a rootDirs overlay so tsc resolves ./*.arv imports against the mirror:

// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "bundler", // Vite's default; see note below
    "rootDirs": ["src", ".arvia/types"],
  },
}

// package.json
{ "scripts": { "typecheck": "tsc --noEmit" } }

Other modes:

• 'sibling' (or true) — writes foo.arv.d.ts next to each source file. Resolved by tsc with no rootDirs, at the cost of files in your src tree.
• false — writes nothing; types come from @arviahq/typescript-plugin (the tsserver plugin + arvia-tsc) instead.

DtsConfig (object form) customizes central mode:

arvia({
  dts: {
    mode: "central", // default when an object is given
    dir: ".arvia/types", // central directory, relative to the Vite root
    sourceRoot: "src", // mirrored source root; must match rootDirs[0]
  },
});

Resolution note. Central/sibling .d.ts files are found via TypeScript's .d.ts-append, which applies under moduleResolution: "bundler" (Vite's default) and node10/classic. It does not apply under node16/nodenext — those consumers should keep moduleResolution: "bundler" or use the tsserver plugin instead.

Generating declarations in CI (arvia gen)

The arvia CLI materializes declarations without running Vite — useful before a CI tsc step:

arvia gen src            # writes .arvia/types/**, prunes stale mirrors
arvia gen src --clean    # wipe the central dir first for a hermetic regen

Flags: --dts-mode central|sibling (default central), --dts-dir <dir> (default .arvia/types), --src-root <dir> (default src), --clean.