mini-next-cpp

基于 C++ 的小型 Next.js 风格框架（支持 SSR / SSG / ISR、插件系统、Edge 运行时适配、CSS-in-JS、图片代理/可选优化）。

更多说明见 doc/usage.md。

安装

本包包含 Node-API 原生扩展，安装时会触发 node-gyp rebuild。

前置依赖：

• Node.js >= 14
• C/C++ 编译工具链（macOS: Xcode Command Line Tools / Linux: build-essential / Windows: VS Build Tools）

npm i mini-next-cpp

快速开始（代码方式）

创建 server.js：

const path = require('path');
const { startMiniNextDevServer } = require('mini-next-cpp');

startMiniNextDevServer({
  port: Number(process.env.PORT || 3000),
  pagesDir: path.join(__dirname, 'pages'),
  publicDir: path.join(__dirname, 'public'),
}).catch((err) => {
  console.error(err);
  process.exit(1);
});

创建 pages/index.js：

function Page(props) {
  return 'hello ' + String(props && props.name ? props.name : 'mini-next-cpp');
}

Page.getServerSideProps = async () => {
  return { props: { name: 'mini-next-cpp' } };
};

module.exports = Page;

启动：

node server.js

脚手架（create-mini-next-app）

npx create-mini-next-app my-app
cd my-app
npm run dev

交互模式（不带参数直接运行，会进入目录/模板/CSS/UI/DB/安装等选择）：

npx create-mini-next-app

常用参数：

npx create-mini-next-app my-app --template music --db sqlite --css tailwind --ui daisyui

说明：

• 生成项目默认包含 react / react-dom 依赖（用于 SSR 渲染）

可选项：

• --template <basic|music>
• --db <none|sqlite>（默认 none）
• --css <none|tailwind|pico|bootstrap>（默认 tailwind）
• --ui <none|daisyui|preline|flowbite>（默认 daisyui）
• --ts
• --no-install

C++ CLI（mn）

安装后可用 mn 简化脚手架命令：

mn create my-app --template music --db sqlite --css tailwind --ui daisyui

交互模式（基于 FTXUI）：

mn

C++ 静态部署服务器（mini-next-serve）

mini-next-serve 是一个极简静态文件服务器（用于部署静态产物/导出目录），示例：

mini-next-serve --dir ./dist --port 3000

访问规则：

• 直接读取 --dir 下的文件
• GET /public/* 会映射到 --dir/public/*
• 当请求文件不存在时，尝试回退到 --dir/index.html（适合 SPA/静态导出）

渲染模式

默认渲染走 JS（React DOM Server）。可通过 SSR_MODE 切换：

• SSR_MODE=js（默认）
• SSR_MODE=native（使用原生 addon 的 renderToString）

示例：

SSR_MODE=native node server.js

原生 JSX 编译（实验）

默认 pages 编译使用 Babel（支持 .js/.jsx/.ts/.tsx）。另外提供一个“原生 JSX -> JS”转换器（C++ 实现），通过环境变量启用：

JSX_COMPILER=native node server.js

说明：

• 仅对 .jsx 启用原生 JSX 编译（.tsx 仍走 Babel），因为 TSX 存在类型语法/泛型等会与 JSX 产生歧义，当前解析器不保证兼容。
• 原生转换会把 JSX 变成 React.createElement(...)，并在需要时注入 React 绑定。

页面数据获取

支持 Next 风格的数据函数：

• getServerSideProps(ctx)：每次请求执行（SSR）
• getStaticProps(ctx)：生产模式下启用 SSG/ISR（根据 revalidate 控制刷新）

getStaticProps 返回格式示例：

Page.getStaticProps = async () => {
  return { props: { n: 1 }, revalidate: 1 };
};

插件系统

在 startMiniNextDevServer/createMiniNextServer 中传入 plugins：

startMiniNextDevServer({
  pagesDir,
  publicDir,
  plugins: [
    {
      onRequest(ctx) {
        if (ctx.urlPath === '/health') {
          return { handled: true, status: 200, body: 'ok' };
        }
      },
      extendPageProps(props, ctx) {
        return { ...props, now: Date.now(), urlPath: ctx.urlPath };
      },
      transformHtml(html) {
        return html.replace('</head>', '<meta name="x" content="y" /></head>');
      },
      getClientScripts() {
        return ['https://example.com/a.js'];
      },
      onNotFound(ctx) {
        return { handled: true, status: 404, body: 'custom 404' };
      },
      onError(ctx) {
        return { handled: true, status: 500, body: 'custom error' };
      },
    },
  ],
});

常见 hook：

• apply(api)：可拿到 Express app 并注册自定义路由
• onStart(api)：服务启动后回调
• onRequest(ctx)：请求进入渲染/静态处理前（支持“控制返回值”短路响应）
• extendPageProps(props, ctx)：注入页面 props（SSR/SSG 都生效）
• transformHtml(html, ctx)：最终 HTML 转换
• getClientScripts(ctx)：注入 <script> 列表
• onNotFound(ctx) / onError(ctx)：404/500 自定义处理
• onDevFileChange(ev)：开发模式文件变化

Edge（createMiniNextEdgeHandler）

可将 pages + plugins 以 Edge 形式运行（fetch(Request) 风格）。示例：

const path = require('path');
const { createMiniNextEdgeHandler } = require('mini-next-cpp');

const handler = createMiniNextEdgeHandler({
  pagesDir: path.join(process.cwd(), 'pages'),
  publicDir: path.join(process.cwd(), 'public'),
  plugins: [],
});

addEventListener('fetch', (event) => {
  event.respondWith(handler(event.request));
});

API

从包中导出：

• startMiniNextDevServer
• createMiniNextServer
• createMiniNextEdgeHandler
• css / runWithStyleRegistry
• renderPage / renderDocument

License

MIT