@mismo/next 0.0.0-stage → 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felix Bernal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @mismo/next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+mismo for Next.js (App Router). [mismo](https://mismo.dev) shares screens, routes and navigation between a React Native app and a web app, each on its own router.
+
+**Docs: [mismo.dev/docs/nextjs](https://mismo.dev/docs/nextjs)**
+
+## Install
+
+```sh
+npm i @mismo/core @mismo/next
+```
+
+## Setup
+
+Wrap the app's Next.js config. It writes the shared routes into `app/` and runs the shared screens' navigation on Next.js:
+
+```ts
+// next.config.ts
+import { withMismo } from "@mismo/next/config";
+
+export default withMismo(
+  { transpilePackages: ["@acme/app", "@mismo/core", "@mismo/next"] },
+  { config: "../../packages/app/routes.config.ts", outDir: "app", types: "app/routes.gen.ts" },
+);
+```
+
+`@acme/app` is your shared package, which Next.js compiles along with mismo. Supports Next.js `>=16 <17`.
+
+See [Getting started](https://mismo.dev/docs/getting-started) for the whole setup: the shared routes package, and each app.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+export interface WithMismoOptions {
+    /** The shared `routes.config.ts`, relative to the app. */
+    config: string;
+    /** The App Router's folder, relative to the app: `app`, or `src/app`. */
+    outDir: string;
+    /** The app's types file, relative to the app. */
+    types: string;
+    /** The app's folder. Next.js loads its config there, so it is `process.cwd()` by default. */
+    cwd?: string;
+}
+/**
+ * Next.js's config for an app on mismo: writes the app's routes into the App Router's folder when
+ * Next.js loads its config (before it reads the folder, for `next dev` and `next build` alike), and
+ * again in dev as route files come and go; and points `@mismo/core` at Next.js's runtime, for Turbopack
+ * and for webpack.
+ *
+ *     export default withMismo({ … }, { config: "../shared/routes.config.ts", outDir: "app", types: "app/routes.gen.ts" });
+ */
+export declare function withMismo<T extends object>(nextConfig: T, { config, outDir, types, cwd }: WithMismoOptions): T;

package/dist/config.js

@@ -0,0 +1,33 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { watchAppRoutes } from "@mismo/core/generate";
+import { output } from "./output.js";
+/**
+ * Next.js's config for an app on mismo: writes the app's routes into the App Router's folder when
+ * Next.js loads its config (before it reads the folder, for `next dev` and `next build` alike), and
+ * again in dev as route files come and go; and points `@mismo/core` at Next.js's runtime, for Turbopack
+ * and for webpack.
+ *
+ *     export default withMismo({ … }, { config: "../shared/routes.config.ts", outDir: "app", types: "app/routes.gen.ts" });
+ */
+export function withMismo(nextConfig, { config, outDir, types, cwd = process.cwd() }) {
+    const next = nextConfig;
+    watchAppRoutes({ config, output: output({ outDir, types }), cwd });
+    // From the app, which depends on this adapter: the shared package importing `@mismo/core` may not.
+    const runtime = createRequire(path.join(cwd, "package.json")).resolve("@mismo/next/runtime");
+    // Turbopack takes a path relative to the app, webpack an absolute one.
+    const relative = `./${path.relative(cwd, runtime).split(path.sep).join("/")}`;
+    const previous = next.webpack;
+    const changed = {
+        turbopack: {
+            ...next.turbopack,
+            resolveAlias: { ...next.turbopack?.resolveAlias, "@mismo/core": relative },
+        },
+        webpack: (webpackConfig, context) => {
+            const config = previous ? previous(webpackConfig, context) : webpackConfig;
+            config.resolve = { ...config.resolve, alias: { ...config.resolve?.alias, "@mismo/core$": runtime } };
+            return config;
+        },
+    };
+    return { ...next, ...changed };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { output } from "./output.js";
+export declare const next: {
+    name: string;
+    rules: import("@mismo/core/generate").RouteRules;
+    output: typeof output;
+};

package/dist/index.js

@@ -0,0 +1,6 @@
+import { output, rules } from "./output.js";
+export const next = {
+    name: "Next.js",
+    rules,
+    output,
+};

package/dist/output.d.ts

@@ -0,0 +1,14 @@
+import { type RouteOutput, type RouteRules } from "@mismo/core/adapter";
+/** What Next.js's App Router cannot express, from its folder conventions. */
+export declare const rules: RouteRules;
+/**
+ * Next.js's files, for a web app on the App Router: the routes folder's layout in `app/`, a
+ * `page.tsx` per page and a `layout.tsx` per layout, next to the app's own (its root `layout.tsx`
+ * among them). The shared screens use hooks, so each file is a client component. A page renders in
+ * a Suspense boundary, which Next.js needs around `useSearchParams` to prerender it; a layout hands
+ * the page Next.js gives it (`children`) to `Slot`.
+ */
+export declare function output({ outDir, types }: {
+    outDir: string;
+    types: string;
+}): RouteOutput;

package/dist/output.js

@@ -0,0 +1,86 @@
+import path from "node:path";
+import { GENERATED, importPath, isGroup, isParam, oneUrlPerPage, placesOf } from "@mismo/core/adapter";
+/** What Next.js's App Router cannot express, from its folder conventions. */
+export const rules = {
+    router: "Next.js",
+    target: "web",
+    check(routes) {
+        // It refuses two pages that resolve to one URL, such as `(a)/about` and `(b)/about`.
+        const problems = oneUrlPerPage(routes, "Next.js");
+        // Folder names it reads as something other than a route, without an error.
+        for (const { route } of placesOf(routes)) {
+            for (const segment of route.segments) {
+                if (isParam(segment))
+                    continue;
+                if (segment.startsWith("_"))
+                    problems.push(`${route.id}: "${segment}" starts with "_", a private folder to Next.js, left out of its routes.`);
+                if (segment.startsWith("@"))
+                    problems.push(`${route.id}: "${segment}" starts with "@", a parallel route's slot to Next.js.`);
+                if (isGroup(segment) && segment.startsWith("(."))
+                    problems.push(`${route.id}: "${segment}" is an intercepting route to Next.js.`);
+            }
+        }
+        return problems;
+    },
+};
+/**
+ * Next.js's files, for a web app on the App Router: the routes folder's layout in `app/`, a
+ * `page.tsx` per page and a `layout.tsx` per layout, next to the app's own (its root `layout.tsx`
+ * among them). The shared screens use hooks, so each file is a client component. A page renders in
+ * a Suspense boundary, which Next.js needs around `useSearchParams` to prerender it; a layout hands
+ * the page Next.js gives it (`children`) to `Slot`.
+ */
+export function output({ outDir, types }) {
+    return {
+        name: "next",
+        target: "web",
+        outDir,
+        types,
+        rules,
+        runtime: "@mismo/next/runtime",
+        emit(routes, context) {
+            const files = new Map();
+            for (const { route, folder } of placesOf(routes)) {
+                const segments = [...folder, ...route.segments].map(toNext);
+                const dirs = route.layout || segments.at(-1) !== "index" ? segments : segments.slice(0, -1);
+                const file = [...dirs, route.layout ? "layout.tsx" : "page.tsx"].join("/");
+                const from = importPath(path.join(context.outDir, file), route.file);
+                files.set(file, route.layout ? layoutFile(from) : pageFile(from));
+            }
+            return files;
+        },
+    };
+}
+/** A segment as Next.js spells it: `:id` is `[id]`. */
+const toNext = (segment) => (isParam(segment) ? `[${segment.slice(1)}]` : segment);
+const pageFile = (from) => `${GENERATED}"use client";
+
+import { Suspense } from "react";
+
+import Page from "${from}";
+
+// Next.js prerenders a page only with a boundary around \`useSearchParams\`.
+export default function MismoPage() {
+  return (
+    <Suspense>
+      <Page />
+    </Suspense>
+  );
+}
+`;
+const layoutFile = (from) => `${GENERATED}"use client";
+
+import { SlotChildren } from "@mismo/next/runtime";
+import type { ReactNode } from "react";
+
+import Layout from "${from}";
+
+// Next.js gives a layout its page as \`children\`: the shared layout renders it with \`Slot\`.
+export default function MismoLayout({ children }: { children: ReactNode }) {
+  return (
+    <SlotChildren value={children}>
+      <Layout />
+    </SlotChildren>
+  );
+}
+`;

package/dist/runtime.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } from "react";
+import { type BackLinkProps, type Href, type LinkProps, type Nav, type Routes, type SearchParams, type To } from "@mismo/core/contract";
+export { pathOf, type BackLinkProps, type Href, type LinkProps, type Nav, type Routes, type SearchParams, type To, } from "@mismo/core/contract";
+/** For the generated `layout.tsx`: the page below the shared layout it renders. */
+export declare function SlotChildren({ value, children }: {
+    value: ReactNode;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Where a layout renders its child route. */
+export declare function Slot(): import("react").JSX.Element;
+/** A real link, so it can be opened in a new tab. Next.js loads its page ahead as it shows. */
+export declare function Link({ to, replace, label, children }: LinkProps): import("react").JSX.Element;
+/**
+ * Goes back when there is somewhere to go back to in this app, and to `fallback` otherwise. A real
+ * link to `fallback`, so a modified click still opens it in a new tab.
+ */
+export declare function BackLink({ fallback, label, children }: BackLinkProps): import("react").JSX.Element;
+/** Navigates as soon as it renders, replacing the current entry. */
+export declare function Redirect({ to }: {
+    to: To;
+}): null;
+export declare function useNav(): Nav;
+/** The current path, such as `/orgs/acme`. */
+export declare function usePathname(): string;
+/** The current route's params. `href` is the route the screen is for, which types them. */
+export declare function useParams<H extends Href>(_href: H): Routes[H];
+/** The query of the current URL. A key given twice is its first value, as on native. */
+export declare function useSearchParams(): SearchParams;

package/dist/runtime.js

@@ -0,0 +1,79 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import NextLink from "next/link";
+import { usePathname as useNextPathname, useParams as useNextParams, useRouter, useSearchParams as useNextSearchParams, } from "next/navigation";
+import { createContext, useContext, useEffect, useMemo } from "react";
+import { pathOf } from "@mismo/core/contract";
+export { pathOf, } from "@mismo/core/contract";
+/**
+ * The page a Next.js layout was given. Next.js passes it as `children`, where other routers render
+ * an outlet: the generated `layout.tsx` provides it, and `Slot` renders it, so a shared layout is
+ * the same on every router.
+ */
+const Children = createContext(null);
+/** For the generated `layout.tsx`: the page below the shared layout it renders. */
+export function SlotChildren({ value, children }) {
+    return _jsx(Children.Provider, { value: value, children: children });
+}
+/** Where a layout renders its child route. */
+export function Slot() {
+    return _jsx(_Fragment, { children: useContext(Children) });
+}
+/** A real link, so it can be opened in a new tab. Next.js loads its page ahead as it shows. */
+export function Link({ to, replace = false, label, children }) {
+    return (_jsx(NextLink, { href: pathOf(to), replace: replace, "aria-label": label, children: children }));
+}
+/**
+ * Whether there is an earlier entry in this site's history to go back to. The Navigation API says
+ * so exactly; without it, any earlier entry counts.
+ */
+function canGoBack() {
+    const browser = globalThis;
+    if (!browser.history)
+        return false;
+    return browser.navigation?.canGoBack ?? browser.history.length > 1;
+}
+/**
+ * Goes back when there is somewhere to go back to in this app, and to `fallback` otherwise. A real
+ * link to `fallback`, so a modified click still opens it in a new tab.
+ */
+export function BackLink({ fallback, label, children }) {
+    const router = useRouter();
+    const onClick = (event) => {
+        if (event.button !== 0 || event.metaKey || event.altKey || event.ctrlKey || event.shiftKey || !canGoBack())
+            return;
+        event.preventDefault();
+        router.back();
+    };
+    return (_jsx(NextLink, { href: pathOf(fallback), "aria-label": label, onClick: onClick, children: children }));
+}
+/** Navigates as soon as it renders, replacing the current entry. */
+export function Redirect({ to }) {
+    const router = useRouter();
+    const path = pathOf(to);
+    useEffect(() => router.replace(path), [router, path]);
+    return null;
+}
+export function useNav() {
+    const router = useRouter();
+    return useMemo(() => ({
+        go: (to) => router.push(pathOf(to)),
+        replace: (to) => router.replace(pathOf(to)),
+        back: () => router.back(),
+        canGoBack,
+        preload: async (to) => router.prefetch(pathOf(to)),
+    }), [router]);
+}
+/** The current path, such as `/orgs/acme`. */
+export function usePathname() {
+    return useNextPathname();
+}
+/** The current route's params. `href` is the route the screen is for, which types them. */
+export function useParams(_href) {
+    return useNextParams();
+}
+/** The query of the current URL. A key given twice is its first value, as on native. */
+export function useSearchParams() {
+    const search = useNextSearchParams();
+    return useMemo(() => Object.fromEntries([...search.keys()].map((key) => [key, search.get(key) ?? undefined])), [search]);
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@mismo/next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.0",
+  "description": "mismo for Next.js (App Router): run shared screens and routes in a Next.js app.",
+  "keywords": [
+    "mismo",
+    "next",
+    "nextjs",
+    "app-router",
+    "routes"
+  ],
+  "homepage": "https://mismo.dev",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "@mismo/core": "^0.1.0-beta.0"
+  },
+  "peerDependencies": {
+    "next": ">=16 <17",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "next": "^16.4.3",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../scripts/fix-declarations.mjs dist"
+  }
 }