vite-plugin-norg

4.0.11 verified Mon Apr 27 auth: no javascript

A Vite plugin that transforms .norg files (Neorg document format) into renderable HTML, React, Svelte, Vue components or metadata. Current stable version is 4.0.11, released weekly. Key differentiator: it bridges the Neorg note-taking ecosystem with modern web frameworks, providing source maps, code syntax highlighting via arborium/tree-sitter, embed components, and full TypeScript type definitions. Supports multiple output modes (html, react, svelte, vue, metadata) with automatic framework detection. Requires Vite 8+, and React/Svelte/Vue peer deps only when using those modes. Compared to generic markdown-to-JSX tools, it is purpose-built for Norg files and leverages Neorg's native parser (WASM/Napi/Rust) for accuracy.

Common errors

error Error: Cannot find module 'vite-plugin-norg' ↓

cause Package not installed or missing from dependencies.

fix

Run npm install -D vite-plugin-norg.

error The plugin './doc.norg' is not a valid Vite plugin. ↓

cause Default import used instead of named import { norgPlugin }.

fix

Change to import { norgPlugin } from 'vite-plugin-norg'.

error Uncaught ReferenceError: Component is not defined ↓

cause Importing from .norg file in wrong mode (e.g., 'html' mode used but expecting React component).

fix

Ensure norgPlugin mode matches the framework (e.g., 'react' for React).

Warnings

breaking Plugin requires Vite 8; will not work with Vite 7 or earlier. ↓

fix Update Vite to ^8.0.0.

breaking Named import { norgPlugin } required; default import no longer works. ↓

fix Use import { norgPlugin } from 'vite-plugin-norg'.

deprecated Vite 6 support dropped in v4. ↓

fix Upgrade to Vite 8.

gotcha Component mode must match the framework; mismatched mode will cause runtime errors (e.g., React file used with 'svelte' mode). ↓

fix Set mode to the same framework as your frontend code.

gotcha JavaScript reserved words in Norg metadata keys (e.g., 'constructor') can break imports. ↓

fix Avoid reserved words as metadata keys.

deprecated The 'metadata' mode (without appending ?metadata) may be removed in v5; prefer using the query parameter. ↓

fix Use import { metadata, toc } from './doc.norg?metadata'.

Install

npm install vite-plugin-norg

yarn add vite-plugin-norg

pnpm add vite-plugin-norg

Imports

norgPlugin

wrong

import norgPlugin from 'vite-plugin-norg'

correct

import { norgPlugin } from 'vite-plugin-norg'

Default export removed in v4; must use named import.

metadata (with html)

wrong

import { metadata } from './doc.norg' (missing html when needed)

correct

import { metadata, html } from './doc.norg'

Metadata types

wrong

import 'vite-plugin-norg' (no global types)

correct

/// <reference types="vite-plugin-norg/html" /> (in d.ts)

Quickstart

Configures Vite with the norg plugin in React mode and demonstrates importing a .norg file as a React component with metadata.

// vite.config.ts
import { defineConfig } from 'vite';
import { norgPlugin } from 'vite-plugin-norg';

export default defineConfig({
  plugins: [
    norgPlugin({ mode: 'react' })
  ]
});

// app.tsx
import { Component, metadata } from './doc.norg';
export default function App() {
  return (
    <div>
      <h1>{metadata.title}</h1>
      <Component />
    </div>
  );
}

// Add to app.d.ts:
/// <reference types="vite-plugin-norg/react" />