{"id":22759,"library":"vite-plugin-norg","title":"vite-plugin-norg","description":"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.","status":"active","version":"4.0.11","language":"javascript","source_language":"en","source_url":"https://github.com/bottd/vite-plugin-norg","tags":["javascript","vite","plugin","norg","neorg","wasm","napi","rust","svelte","typescript"],"install":[{"cmd":"npm install vite-plugin-norg","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-norg","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-norg","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for 'react' mode; peer dependency since v4.","package":"react","optional":true},{"reason":"Required for 'svelte' mode; peer dependency since v4.","package":"svelte","optional":true},{"reason":"Required for 'vue' mode; peer dependency since v4.","package":"vue","optional":true},{"reason":"Runtime peer dependency; plugin requires Vite 8+.","package":"vite","optional":false}],"imports":[{"note":"Default export removed in v4; must use named import.","wrong":"import norgPlugin from 'vite-plugin-norg'","symbol":"norgPlugin","correct":"import { norgPlugin } from 'vite-plugin-norg'"},{"wrong":"import { metadata } from './doc.norg' (missing html when needed)","symbol":"metadata (with html)","correct":"import { metadata, html } from './doc.norg'"},{"wrong":"import 'vite-plugin-norg' (no global types)","symbol":"Metadata types","correct":"/// <reference types=\"vite-plugin-norg/html\" /> (in d.ts)"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport { norgPlugin } from 'vite-plugin-norg';\n\nexport default defineConfig({\n  plugins: [\n    norgPlugin({ mode: 'react' })\n  ]\n});\n\n// app.tsx\nimport { Component, metadata } from './doc.norg';\nexport default function App() {\n  return (\n    <div>\n      <h1>{metadata.title}</h1>\n      <Component />\n    </div>\n  );\n}\n\n// Add to app.d.ts:\n/// <reference types=\"vite-plugin-norg/react\" />","lang":"typescript","description":"Configures Vite with the norg plugin in React mode and demonstrates importing a .norg file as a React component with metadata."},"warnings":[{"fix":"Update Vite to ^8.0.0.","message":"Plugin requires Vite 8; will not work with Vite 7 or earlier.","severity":"breaking","affected_versions":"<4.0.0"},{"fix":"Use import { norgPlugin } from 'vite-plugin-norg'.","message":"Named import { norgPlugin } required; default import no longer works.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to Vite 8.","message":"Vite 6 support dropped in v4.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Set mode to the same framework as your frontend code.","message":"Component mode must match the framework; mismatched mode will cause runtime errors (e.g., React file used with 'svelte' mode).","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Avoid reserved words as metadata keys.","message":"JavaScript reserved words in Norg metadata keys (e.g., 'constructor') can break imports.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use import { metadata, toc } from './doc.norg?metadata'.","message":"The 'metadata' mode (without appending ?metadata) may be removed in v5; prefer using the query parameter.","severity":"deprecated","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run npm install -D vite-plugin-norg.","cause":"Package not installed or missing from dependencies.","error":"Error: Cannot find module 'vite-plugin-norg'"},{"fix":"Change to import { norgPlugin } from 'vite-plugin-norg'.","cause":"Default import used instead of named import { norgPlugin }.","error":"The plugin './doc.norg' is not a valid Vite plugin."},{"fix":"Ensure norgPlugin mode matches the framework (e.g., 'react' for React).","cause":"Importing from .norg file in wrong mode (e.g., 'html' mode used but expecting React component).","error":"Uncaught ReferenceError: Component is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}