mirai-core

Mirai.js compiler and development server. Node.js 18 or newer is required.

Create a project

Use the separate project generator. mirai-core is the framework runtime/compiler; its install does not create a project or run an install hook.

npm create mirai@latest

The create-mirai initializer asks for a project name, creates a child directory, writes package.json, mirai.config.json, public/, src/layout/layout.mirai, and src/pages/index.mirai, then installs the generated project's dependencies. You can also pass the name directly: npm create mirai@latest -- my-site.

Mirai files use a mirai [...] frontmatter block. site { name "..."; domain "https://example.com"; language "ja"; } defines the site's identity and canonical domain. This is separate from meta { ... }, which emits HTML metadata such as Twitter cards and Open Graph images. Page titles and descriptions can be set in seo { ... }. A page selects a layout with layout "../layout/layout.mirai";; the <layout>...</layout> wrapper supplies its content to the layout's <switch /> slot. HTML is the default output, while filetype is "php"; opts into PHP output. reload is "client"; enables client navigation and reload is "full"; uses full document loads. Use standard imports for .mirai components, CSS, and browser modules; CSS is bundled inline and JavaScript/TypeScript modules are bundled for the browser.

Frontmatter also supports Node.js JavaScript/TypeScript at build time. Relative and bare NPM imports are loaded on the Node side, including asynchronous getStaticPaths() calls for dynamic route files:

mirai [
  import { marked } from "marked";
  const html = marked("## Rendered at build time");
]
<article>{html}</article>

For example, a file at src/pages/blog/[id].mirai can export async function getStaticPaths() returning entries with params and props; each entry is written to its own route. Page props are available as Mirai.props (Astro.props is also accepted as a migration alias). Use <slot /> in an imported .mirai component to place its children, and set:html={value} when inserting trusted HTML. Browser modules belong in <script> tags or imports marked with & [all]. React component packages can be used when the project has react and react-dom installed; imported components can be written as tags such as <Icon size={24} /> and are rendered to static HTML. This supports React components that can render on the server; it does not hydrate interactive components in the browser.

Commands

npm run dev
npm run build

Normal builds preserve PHP output. Static hosting targets fail if PHP output is present.

Deployment settings

Generated projects provide the conventional npm run build script. They do not override hosting-provider build or deploy commands. Cloudflare Workers Builds can use its default deploy command (npx wrangler deploy); the generated project's prepare script builds assets during dependency installation because the Cloudflare build command is optional by default. Vercel uses its normal build detection. mirai build detects Cloudflare/Vercel build environments and rejects PHP pages there; ordinary builds continue to allow PHP output. Commit the generated project config and Mirai source files with the project.

API

import { build, dev, parseMiraiBlock } from 'mirai-core';

await build({ projectRoot: process.cwd() });

The published package contains prebuilt dist/ files. prepack builds them when creating the package tarball; package installation does not require a build lifecycle script.