MN Rails is the modern scaffold for MarginNote add-ons. It handles project creation, building, packaging, and deployment, and it ships a rich set of templates and scaffolds to get you productive quickly.

Creating a project

Create a project with the create command:

npm create mn-rails@latest

pnpm create mn-rails@latest

yarn create mn-rails

bun create mn-rails

The command runs interactively:

❮ pnpm create mn-rails@latest
? Select a framework
❯ React (React 19 + TypeScript + Vite)
  Vue (Vue 3 + TypeScript + Vite)
  Svelte (Svelte 5 + TypeScript + Vite)

↑↓ navigate • ⏎ select

Non-interactive creation

Every option can be passed on the command line:

npx mn-rails@latest init my-addon \
  --framework react \
  --kind panel \
  --addonid com.example.my-addon \
  --author Example \
  --title "My Add-on" \
  --package-manager pnpm \
  --no-git # not recommend

An explicitly specified target directory must be empty. If you omit the directory and the current directory contains visible files, the command creates a subdirectory after you confirm its name.

Frameworks and add-on shapes

Framework	What the template includes
React	React 19, TypeScript, and Vite
Vue	Vue 3, TypeScript, and Vite
Svelte	Svelte 5, TypeScript, and Vite

Two add-on shapes are available:

Panel only: a standard scene add-on whose page entry is index.html. MarginNote generates the add-on panel and menus from mnaddon.json.
Hybrid: a combination of a scene add-on and a classic add-on, with a web page and a two-way bridge module. See Beyond the panel.

Project structure

my-addon

index.html

mnaddon.json

eslint.config.mjs

vite.config.ts

package.json

eslint

src

App.tsx

main.tsx

bridge.ts

public

template

native

native/ exists only in hybrid projects. Panel-only projects do not create this directory, and their build output must not contain a root-level main.js. Key files and what they do:

Path	Purpose
`index.html`	Panel entry.
`mnaddon.json`	Add-on manifest: identity, name, version, entry, and events.
`eslint.config.mjs`	Shared ESLint configuration.
`eslint/framework.mjs`	Framework rules for React, Vue, or Svelte.
`src/`	React, Vue, or Svelte page code.
`public/`	Static assets copied verbatim to the build output root by Vite.
`template/template.json`	Scene template configuration.
`template/localizations.json`	Localized display names for the scene template.
`vite.config.ts`	Vite configuration.

Project commands

The project provides the following scripts:

Command	Purpose
`lint`	Runs ESLint with the framework’s recommended rules.
`lint:fix`	Fixes ESLint issues automatically where possible.
`typecheck`	Runs type checking for the current framework.
`check`	Runs ESLint and then type checking.
`build`	Builds the page with Vite and validates the add-on directory and `/pkg/` references.
`package`	Produces the `.mnaddon` and `.mntemplate` installers.
`sync`	Copies the build output into the local MarginNote and restarts the app.
`doctor`	Checks the project, the build output, and the MarginNote environment.

npm run lint
npm run lint:fix
npm run typecheck
npm run check
npm run build
npm run package
npm run sync
npm run doctor

pnpm lint
pnpm lint:fix
pnpm typecheck
pnpm check
pnpm build
pnpm package
pnpm sync
pnpm doctor

yarn lint
yarn lint:fix
yarn typecheck
yarn check
yarn build
yarn package
yarn sync
yarn doctor

Building and deploying

First build:

npm run build

pnpm build

yarn build

The build output goes to dist/. Both package and sync require an existing dist/ that passes the output checks. Local deployment:

npm run sync

pnpm sync

yarn sync

sync performs these steps:

Verifies that dist/ matches the current add-on shape.
Locates the local MarginNote add-on directory.
Replaces files through a temporary directory, restoring the previous add-on if anything fails.
Restarts MarginNote.

Local deployment is supported on macOS only.

Producing installers

npm run package

pnpm package

yarn package

Installers are written to release/:

<addon-name>-<version>.mnaddon: the compressed add-on directory.
<template-name>-<version>.mntemplate: a scene template package containing the template configuration, localization files, and add-on files.

For how to write template configuration, see Minimal package and Adding add-ons.

Getting Started

Basics

Add-ons In-Depth

Creating an add-on project with MN Rails