Registry / web-framework / vite-plugin-norg

vite-plugin-norg

library4.0.11jsnpmunverified

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.

web-framework serialization

npm install vite-plugin-norg

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-NORG

vite-plugin-norg

web-frameworkjavascriptv4.0.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

norgPlugin

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

✗ import norgPlugin from 'vite-plugin-norg'

Default export removed in v4; must use named import.

metadata (with html)

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

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

Metadata types

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

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

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" />

Debug

Known issues

breakingPlugin requires Vite 8; will not work with Vite 7 or earlier.

fix

Update Vite to ^8.0.0.

affects: <4.0.0

breakingNamed import { norgPlugin } required; default import no longer works.

fix

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

affects: >=4.0.0

deprecatedVite 6 support dropped in v4.

fix

Upgrade to Vite 8.

affects: >=4.0.0

gotchaComponent 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.

affects: >=0.0.0

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

fix

Avoid reserved words as metadata keys.

affects: >=0.0.0

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

fix

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

affects: >=4.0.0

Errors

Common errors & fixes

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

Package not installed or missing from dependencies.

fix

Run npm install -D vite-plugin-norg.

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

Default import used instead of named import { norgPlugin }.

fix

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

Uncaught ReferenceError: Component is not defined

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).

Upgrade

Version history

4.0.11latest on npm

Audit

Dependencies

reactoptionalRequired for 'react' mode; peer dependency since v4.

svelteoptionalRequired for 'svelte' mode; peer dependency since v4.

vueoptionalRequired for 'vue' mode; peer dependency since v4.

viterequiredRuntime peer dependency; plugin requires Vite 8+.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bottd/vite-plugin-norg ↗

packagehttps://www.npmjs.com/package/vite-plugin-norg ↗

homepagehttps://norg-js.github.io/vite-plugin-norg ↗