@finesoft/create-app 0.1.0

package/templates/react/src/lib/guards/auth.ts

@@ -0,0 +1,17 @@
+import { type BeforeLoadGuard, next, redirect } from "@finesoft/front";
+
+/**
+ * Auth guard — redirects unauthenticated users to login.
+ *
+ * Demonstrates beforeLoad middleware with `redirect()` and `next()`.
+ * In a real app, check a session cookie or token via `ctx.getCookie()`.
+ */
+export const authGuard: BeforeLoadGuard = (ctx) => {
+    const token = ctx.getCookie("auth_token");
+
+    if (!token) {
+        return redirect(`/login?from=${encodeURIComponent(ctx.url)}`);
+    }
+
+    return next();
+};

package/templates/react/src/lib/guards/seo.ts

@@ -0,0 +1,15 @@
+import { type AfterLoadGuard, next, rewrite } from "@finesoft/front";
+
+/**
+ * SEO guard — normalizes URLs after data load.
+ *
+ * Demonstrates afterLoad middleware with `rewrite()`.
+ * Strips trailing slashes for canonical URL consistency.
+ */
+export const seoGuard: AfterLoadGuard = (ctx) => {
+    if (ctx.path !== "/" && ctx.path.endsWith("/")) {
+        return rewrite(ctx.path.slice(0, -1));
+    }
+
+    return next();
+};

package/templates/react/src/lib/mappers/product.ts

@@ -0,0 +1,27 @@
+import { makeFlowAction, mapEach, type Mapper } from "@finesoft/front";
+import type { ProductItem } from "../models/product";
+
+/** Raw API response shape */
+interface ApiProduct {
+    id: number;
+    title: string;
+    price: number;
+    thumbnail?: string;
+}
+
+/** Transform raw API product → domain ProductItem */
+const toProductItem: Mapper<ApiProduct, ProductItem> = (raw) => ({
+    id: String(raw.id),
+    itemType: "product",
+    name: raw.title,
+    price: raw.price,
+    imageUrl: raw.thumbnail ?? "/img/placeholder.svg",
+    clickAction: makeFlowAction(`/products/${raw.id}`),
+});
+
+/**
+ * Composed mapper pipeline: ApiProduct[] → ProductItem[]
+ *
+ * Demonstrates pipe() + mapEach() for data transformation.
+ */
+export const mapProducts: Mapper<ApiProduct[], ProductItem[]> = mapEach(toProductItem);

package/templates/react/src/lib/models/product.ts

@@ -0,0 +1,48 @@
+import type { BaseItem, BasePage, BaseShelf } from "@finesoft/front";
+
+export interface ProductItem extends BaseItem {
+    itemType: "product";
+    name: string;
+    price: number;
+    imageUrl: string;
+}
+
+export interface ProductShelf extends BaseShelf {
+    shelfType: "products";
+    items: ProductItem[];
+}
+
+export interface HomePage extends BasePage {
+    pageType: "home";
+    shelves: ProductShelf[];
+}
+
+export interface ProductPage extends BasePage {
+    pageType: "product";
+    product: {
+        id: string;
+        name: string;
+        price: number;
+        description: string;
+        imageUrl: string;
+    };
+}
+
+export interface SearchPage extends BasePage {
+    pageType: "search";
+    query: string;
+    results: ProductItem[];
+}
+
+export interface AboutPage extends BasePage {
+    pageType: "about";
+    content: string;
+}
+
+export interface ErrorPage extends BasePage {
+    pageType: "error";
+    status: number;
+}
+
+/** 所有页面类型联合 */
+export type AppPage = HomePage | ProductPage | SearchPage | AboutPage | ErrorPage;

package/templates/react/src/lib/services/api-client.ts

@@ -0,0 +1,28 @@
+import { HttpClient, type HttpClientConfig } from "@finesoft/front";
+
+/**
+ * Demo API client — extends HttpClient for typed endpoint access.
+ *
+ * Showcases HttpClient subclass pattern with base URL and custom fetch.
+ */
+export class ApiClient extends HttpClient {
+    constructor(config?: Partial<HttpClientConfig>) {
+        super({
+            baseUrl: config?.baseUrl ?? "/api",
+            defaultHeaders: { "Content-Type": "application/json", ...config?.defaultHeaders },
+            fetch: config?.fetch,
+        });
+    }
+
+    async getProducts(): Promise<unknown[]> {
+        return this.get<unknown[]>("/products");
+    }
+
+    async getProduct(id: string): Promise<unknown> {
+        return this.get<unknown>(`/products/${id}`);
+    }
+
+    async searchProducts(query: string): Promise<unknown[]> {
+        return this.get<unknown[]>("/products", { q: query });
+    }
+}

package/templates/react/src/main.tsx

@@ -0,0 +1,49 @@
+import { startBrowserApp, type Action, type BasePage, type Framework } from "@finesoft/front";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+import { bootstrap } from "./bootstrap";
+import type { AppPage } from "./lib/models/product";
+
+void startBrowserApp({
+    bootstrap,
+    mountId: "app",
+    mount: (target: HTMLElement, { framework }: { framework: Framework; locale: string }) => {
+        let root: ReturnType<typeof createRoot> | null = null;
+        let currentPage: AppPage | null = null;
+
+        function render(page: AppPage | null, loading: boolean) {
+            const handleAction = (action: Action) => {
+                void framework.perform(action);
+            };
+            if (!root) root = createRoot(target);
+            root.render(<App page={page} loading={loading} onAction={handleAction} />);
+        }
+
+        return ({
+            page,
+            isFirstPage,
+        }: {
+            page: Promise<BasePage> | BasePage;
+            isFirstPage?: boolean;
+        }) => {
+            if (page instanceof Promise) {
+                if (!isFirstPage) render(currentPage, true);
+                void page.then((p) => {
+                    currentPage = p as AppPage;
+                    render(currentPage, false);
+                });
+            } else {
+                currentPage = page as AppPage;
+                render(currentPage, false);
+            }
+        };
+    },
+    callbacks: {
+        onNavigate(pathname) {
+            console.log("[navigate]", pathname);
+        },
+        onModal(page) {
+            console.log("[modal]", page.title);
+        },
+    },
+});

package/templates/react/src/pages/About.tsx

@@ -0,0 +1,16 @@
+import type { Action } from "@finesoft/front";
+import type { AboutPage } from "../lib/models/product";
+
+interface AboutProps {
+    page: AboutPage;
+    onAction?: (action: Action) => void;
+}
+
+export default function About({ page }: AboutProps) {
+    return (
+        <div>
+            <h1>{page.title}</h1>
+            <p>{page.content}</p>
+        </div>
+    );
+}

package/templates/react/src/pages/Home.tsx

@@ -0,0 +1,34 @@
+import type { Action } from "@finesoft/front";
+import ProductCard from "../components/ProductCard";
+import type { HomePage } from "../lib/models/product";
+
+interface HomeProps {
+    page: HomePage;
+    onAction?: (action: Action) => void;
+}
+
+export default function Home({ page, onAction }: HomeProps) {
+    return (
+        <div>
+            <h1>{page.title}</h1>
+            <p>{page.description}</p>
+            {page.shelves.map((shelf) => (
+                <section key={shelf.id}>
+                    <h2>{shelf.title}</h2>
+                    <div
+                        style={{
+                            display: "flex",
+                            gap: "1rem",
+                            flexWrap: shelf.isHorizontal ? "nowrap" : "wrap",
+                            overflowX: shelf.isHorizontal ? "auto" : undefined,
+                        }}
+                    >
+                        {shelf.items.map((item) => (
+                            <ProductCard key={item.id} item={item} onAction={onAction} />
+                        ))}
+                    </div>
+                </section>
+            ))}
+        </div>
+    );
+}

package/templates/react/src/pages/NotFound.tsx

@@ -0,0 +1,25 @@
+import type { Action } from "@finesoft/front";
+import { makeFlowAction } from "@finesoft/front";
+import type { ErrorPage } from "../lib/models/product";
+
+interface NotFoundProps {
+    page: ErrorPage;
+    onAction?: (action: Action) => void;
+}
+
+export default function NotFound({ page, onAction }: NotFoundProps) {
+    const handleHome = (e: React.MouseEvent) => {
+        e.preventDefault();
+        onAction?.(makeFlowAction("/"));
+    };
+
+    return (
+        <div>
+            <h1>{page.title}</h1>
+            <p>{page.description}</p>
+            <a href="/" onClick={handleHome}>
+                ← Go Home
+            </a>
+        </div>
+    );
+}

package/templates/react/src/pages/ProductDetail.tsx

@@ -0,0 +1,34 @@
+import type { Action } from "@finesoft/front";
+import { makeFlowAction } from "@finesoft/front";
+import type { ProductPage } from "../lib/models/product";
+
+interface ProductDetailProps {
+    page: ProductPage;
+    onAction?: (action: Action) => void;
+}
+
+export default function ProductDetail({ page, onAction }: ProductDetailProps) {
+    const handleBack = (e: React.MouseEvent) => {
+        e.preventDefault();
+        onAction?.(makeFlowAction("/"));
+    };
+
+    return (
+        <div>
+            <a href="/" onClick={handleBack}>
+                ← Back
+            </a>
+            <h1>{page.product.name}</h1>
+            <p
+                style={{
+                    fontSize: "1.5rem",
+                    color: "#007bff",
+                    fontWeight: "bold",
+                }}
+            >
+                ${page.product.price.toFixed(2)}
+            </p>
+            <p>{page.product.description}</p>
+        </div>
+    );
+}

package/templates/react/src/pages/Search.tsx

@@ -0,0 +1,23 @@
+import type { Action } from "@finesoft/front";
+import ProductCard from "../components/ProductCard";
+import type { SearchPage } from "../lib/models/product";
+
+interface SearchProps {
+    page: SearchPage;
+    onAction?: (action: Action) => void;
+}
+
+export default function Search({ page, onAction }: SearchProps) {
+    return (
+        <div>
+            <h1>{page.title}</h1>
+            <p>{page.description}</p>
+            <div style={{ display: "flex", gap: "1rem", flexWrap: "wrap" }}>
+                {page.results.map((item) => (
+                    <ProductCard key={item.id} item={item} onAction={onAction} />
+                ))}
+            </div>
+            {page.results.length === 0 && <p>No products found.</p>}
+        </div>
+    );
+}

package/templates/react/src/ssr.tsx

@@ -0,0 +1,23 @@
+import { createSSRRender, serializeServerData } from "@finesoft/front";
+import { renderToString } from "react-dom/server";
+import App from "./App";
+import { bootstrap } from "./bootstrap";
+import { getErrorPage } from "./lib/controllers/error";
+import type { AppPage } from "./lib/models/product";
+
+export { serializeServerData };
+
+export const render = createSSRRender({
+    bootstrap,
+    getErrorPage,
+    renderApp(page, _locale) {
+        const html = renderToString(<App page={page as AppPage} />);
+        return {
+            html,
+            head: `<title>${page.title}</title><meta name="description" content="${
+                page.description ?? ""
+            }">`,
+            css: "",
+        };
+    },
+});

package/templates/react/tsconfig.json

@@ -0,0 +1,17 @@
+{
+    "compilerOptions": {
+        "strict": true,
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "jsx": "react-jsx",
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "skipLibCheck": true,
+        "noEmit": true,
+        "paths": {
+            "@/*": ["./src/*"]
+        }
+    },
+    "include": ["src/**/*", "env.d.ts"]
+}

package/templates/react/vite.config.ts

@@ -0,0 +1,20 @@
+import { finesoftFrontViteConfig } from "@finesoft/front";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+    plugins: [
+        react(),
+        finesoftFrontViteConfig({
+            ssr: { entry: "src/ssr.tsx" },
+            locales: ["en", "zh"],
+            defaultLocale: "en",
+            proxies: [
+                {
+                    prefix: "/api",
+                    target: "https://jsonplaceholder.typicode.com",
+                },
+            ],
+        }),
+    ],
+});

package/templates/react-minimal/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/react-minimal/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="<!--ssr-lang-->">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <!--ssr-head-->
+    </head>
+    <body>
+        <div id="app"><!--ssr-body--></div>
+        <!--ssr-data-->
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>

package/templates/react-minimal/package.json

@@ -0,0 +1,21 @@
+{
+    "name": "finesoft-react-minimal",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "vp dev",
+        "build": "vp build",
+        "preview": "vp preview"
+    },
+    "dependencies": {
+        "@finesoft/front": "workspace:*",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
+    },
+    "devDependencies": {
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "@vitejs/plugin-react": "^4.0.0",
+        "vite-plus": "catalog:"
+    }
+}

package/templates/react-minimal/src/App.tsx

@@ -0,0 +1,22 @@
+import type { Action, BasePage } from "@finesoft/front";
+
+interface AppProps {
+    page?: BasePage | null;
+    loading?: boolean;
+    onAction?: (action: Action) => void;
+}
+
+export default function App({ page, loading = false }: AppProps) {
+    if (loading)
+        return (
+            <main style={{ padding: "2rem", textAlign: "center", color: "#999" }}>Loading…</main>
+        );
+    if (!page) return null;
+
+    return (
+        <main style={{ padding: "1rem" }}>
+            <h1>{page.title}</h1>
+            <p>{page.description}</p>
+        </main>
+    );
+}

package/templates/react-minimal/src/bootstrap.ts

@@ -0,0 +1,6 @@
+import { type Framework, defineRoutes } from "@finesoft/front";
+import { HomeController } from "./lib/controllers/home";
+
+export function bootstrap(framework: Framework): void {
+    defineRoutes(framework, [{ path: "/", intentId: "home", controller: new HomeController() }]);
+}

package/templates/react-minimal/src/lib/controllers/home.ts

@@ -0,0 +1,14 @@
+import { BaseController, type BasePage } from "@finesoft/front";
+
+export class HomeController extends BaseController<Record<string, string>, BasePage> {
+    readonly intentId = "home";
+
+    execute(): BasePage {
+        return {
+            id: "home",
+            pageType: "home",
+            title: "Home",
+            description: "Welcome to Finesoft Front",
+        };
+    }
+}

package/templates/react-minimal/src/main.tsx

@@ -0,0 +1,44 @@
+import { startBrowserApp, type Action, type BasePage, type Framework } from "@finesoft/front";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+import { bootstrap } from "./bootstrap";
+
+void startBrowserApp({
+    bootstrap,
+    mountId: "app",
+    mount: (target: HTMLElement, { framework }: { framework: Framework; locale: string }) => {
+        let root: ReturnType<typeof createRoot> | null = null;
+        let currentPage: BasePage | null = null;
+
+        function render(page: BasePage | null, loading: boolean) {
+            const handleAction = (action: Action) => {
+                void framework.perform(action);
+            };
+            if (!root) root = createRoot(target);
+            root.render(<App page={page} loading={loading} onAction={handleAction} />);
+        }
+
+        return ({
+            page,
+            isFirstPage,
+        }: {
+            page: Promise<BasePage> | BasePage;
+            isFirstPage?: boolean;
+        }) => {
+            if (page instanceof Promise) {
+                if (!isFirstPage) render(currentPage, true);
+                void page.then((p) => {
+                    currentPage = p;
+                    render(currentPage, false);
+                });
+            } else {
+                currentPage = page;
+                render(currentPage, false);
+            }
+        };
+    },
+    callbacks: {
+        onNavigate() {},
+        onModal() {},
+    },
+});

package/templates/react-minimal/src/ssr.tsx

@@ -0,0 +1,25 @@
+import { createSSRRender, serializeServerData } from "@finesoft/front";
+import { renderToString } from "react-dom/server";
+import App from "./App";
+import { bootstrap } from "./bootstrap";
+
+export const render = createSSRRender({
+    bootstrap,
+    getErrorPage(status, message) {
+        return {
+            id: "error",
+            pageType: "error",
+            title: `Error ${status}`,
+            description: message,
+        };
+    },
+    renderApp(page, _locale) {
+        return {
+            html: renderToString(<App page={page} />),
+            head: `<title>${page.title}</title>`,
+            css: "",
+        };
+    },
+});
+
+export { serializeServerData };

package/templates/react-minimal/tsconfig.json

@@ -0,0 +1,17 @@
+{
+    "compilerOptions": {
+        "strict": true,
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "jsx": "react-jsx",
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "skipLibCheck": true,
+        "noEmit": true,
+        "paths": {
+            "@/*": ["./src/*"]
+        }
+    },
+    "include": ["src/**/*", "env.d.ts"]
+}

package/templates/react-minimal/vite.config.ts

@@ -0,0 +1,12 @@
+import { finesoftFrontViteConfig } from "@finesoft/front";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+    plugins: [
+        react(),
+        finesoftFrontViteConfig({
+            ssr: { entry: "src/ssr.tsx" },
+        }),
+    ],
+});

package/templates/svelte/env.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+/// <reference types="svelte" />
+
+declare module "*.svelte" {
+    import type { ComponentType, SvelteComponent } from "svelte";
+
+    const component: ComponentType<SvelteComponent>;
+    export default component;
+}

package/templates/svelte/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="<!--ssr-lang-->">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <!--ssr-head-->
+    </head>
+    <body>
+        <div id="app"><!--ssr-body--></div>
+        <!--ssr-data-->
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>

package/templates/svelte/package.json

@@ -0,0 +1,18 @@
+{
+    "name": "finesoft-svelte",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "vp dev",
+        "build": "vp build",
+        "preview": "vp preview"
+    },
+    "dependencies": {
+        "@finesoft/front": "workspace:*",
+        "svelte": "^5.0.0"
+    },
+    "devDependencies": {
+        "@sveltejs/vite-plugin-svelte": "^5.0.0",
+        "vite-plus": "catalog:"
+    }
+}