funstack-static/packages/static/src/plugin/index.ts at cc996c8bb25bd7ee9fd94b00e8023dae28d3d821 · uhyo/funstack-static · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
import path from "node:path";
import type { Plugin } from "vite";
import rsc from "@vitejs/plugin-rsc";
import { buildApp } from "../build/buildApp";
import { serverPlugin } from "./server";
import { defaultRscPayloadDir } from "../rsc/rscModule";

interface FunstackStaticBaseOptions {
  /**
   * Output directory for build.
   *
   * @default dist/public
   */
  publicOutDir?: string;
  /**
   * Enable server-side rendering of the App component.
   * When false, only the Root shell is SSR'd and the App renders client-side.
   * When true, both Root and App are SSR'd and the client hydrates.
   *
   * @default false
   */
  ssr?: boolean;
  /**
   * Path to a module that runs on the client side before React hydration.
   * Use this for client-side instrumentation like Sentry, analytics, or feature flags.
   * The module is imported for its side effects only (no exports needed).
   */
  clientInit?: string;
  /**
   * Directory name used for RSC payload files in the build output.
   * The final path will be `/funstack__/{rscPayloadDir}/{hash}.txt`.
   *
   * Change this if your hosting platform has issues with the default
   * directory name (e.g. Cloudflare Workers redirects URLs containing colons).
   *
   * The value is used as a marker for string replacement during the build
   * process, so it should be unique enough that it does not appear in your
   * application's source code.
   *
   * @default "fun:rsc-payload"
   */
  rscPayloadDir?: string;
}

interface SingleEntryOptions {
  /**
   * Root component of the page.
   * The file should `export default` a React component that renders the whole page.
   * (`<html>...</html>`).
   */
  root: string;
  /**
   * Entry point of your application.
   * The file should `export default` a React component that renders the application content.
   */
  app: string;
  entries?: never;
}

interface MultipleEntriesOptions {
  root?: never;
  app?: never;
  /**
   * Path to a module that exports a function returning entry definitions.
   * Mutually exclusive with `root`+`app`.
   */
  entries: string;
}

export type FunstackStaticOptions = FunstackStaticBaseOptions &
  (SingleEntryOptions | MultipleEntriesOptions);

export default function funstackStatic(
  options: FunstackStaticOptions,
): (Plugin | Plugin[])[] {
  const {
    publicOutDir = "dist/public",
    ssr = false,
    clientInit,
    rscPayloadDir = defaultRscPayloadDir,
  } = options;

  // Validate rscPayloadDir to prevent path traversal or invalid segments
  if (
    !rscPayloadDir ||
    rscPayloadDir.includes("/") ||
    rscPayloadDir.includes("\\") ||
    rscPayloadDir === ".." ||
    rscPayloadDir === "."
  ) {
    throw new Error(
      `[funstack] Invalid rscPayloadDir: "${rscPayloadDir}". Must be a non-empty single path segment without slashes.`,
    );
  }

  let resolvedEntriesModule: string = "__uninitialized__";
  let resolvedClientInitEntry: string | undefined;

  // Determine whether user specified entries or root+app
  const isMultiEntry = "entries" in options && options.entries !== undefined;

  return [
    {
      name: "@funstack/static:config-pre",
      // Placed early because the rsc plugin sets the outDir to the default value
      config(config) {
        return {
          environments: {
            client: {
              build: {
                outDir:
                  config.environments?.client?.build?.outDir ?? publicOutDir,
              },
            },
          },
        };
      },
    },
    serverPlugin(),
    rsc({
      entries: {
        rsc: "@funstack/static/entries/rsc",
        ssr: "@funstack/static/entries/ssr",
        client: "@funstack/static/entries/client",
      },
      serverHandler: false,
    }),
    {
      name: "@funstack/static:config",
      configResolved(config) {
        if (isMultiEntry) {
          resolvedEntriesModule = path.resolve(config.root, options.entries);
        } else {
          // For single-entry, we store both resolved paths to generate a
          // synthetic entries module in the virtual module loader.
          const resolvedRoot = path.resolve(config.root, options.root);
          const resolvedApp = path.resolve(config.root, options.app);
          // Encode as JSON for safe embedding in generated code
          resolvedEntriesModule = JSON.stringify({
            root: resolvedRoot,
            app: resolvedApp,
          });
        }
        if (clientInit) {
          resolvedClientInitEntry = path.resolve(config.root, clientInit);
        }
      },
      configEnvironment(_name, config) {
        if (!config.optimizeDeps) {
          config.optimizeDeps = {};
        }
        // Needed for properly bundling @vitejs/plugin-rsc for browser.
        // See: https://github.com/vitejs/vite-plugin-react/tree/79bf57cc8b9c77e33970ec2e876bd6d2f1568d5d/packages/plugin-rsc#using-vitejsplugin-rsc-as-a-framework-packages-dependencies
        if (config.optimizeDeps.include) {
          config.optimizeDeps.include = config.optimizeDeps.include.map(
            (entry) => {
              if (entry.startsWith("@vitejs/plugin-rsc")) {
                entry = `@funstack/static > ${entry}`;
              }
              return entry;
            },
          );
        }
        if (!config.optimizeDeps.exclude) {
          config.optimizeDeps.exclude = [];
        }
        // Since code includes imports to virtual modules, we need to exclude
        // us from Optimize Deps.
        config.optimizeDeps.exclude.push("@funstack/static");
      },
    },
    {
      name: "@funstack/static:virtual-entry",
      resolveId(id) {
        if (id === "virtual:funstack/entries") {
          return "\0virtual:funstack/entries";
        }
        if (id === "virtual:funstack/config") {
          return "\0virtual:funstack/config";
        }
        if (id === "virtual:funstack/client-init") {
          return "\0virtual:funstack/client-init";
        }
      },
      load(id) {
        if (id === "\0virtual:funstack/entries") {
          if (isMultiEntry) {
            // Re-export the user's entries module
            return `export { default } from "${resolvedEntriesModule}";`;
          }
          // Synthesize a single-entry array from root+app
          const { root, app } = JSON.parse(resolvedEntriesModule);
          return [
            `import Root from "${root}";`,
            `import App from "${app}";`,
            `export default function getEntries() {`,
            `  return [{ path: "index.html", root: { default: Root }, app: { default: App } }];`,
            `}`,
          ].join("\n");
        }
        if (id === "\0virtual:funstack/config") {
          return [
            `export const ssr = ${JSON.stringify(ssr)};`,
            `export const rscPayloadDir = ${JSON.stringify(rscPayloadDir)};`,
          ].join("\n");
        }
        if (id === "\0virtual:funstack/client-init") {
          if (resolvedClientInitEntry) {
            return `import "${resolvedClientInitEntry}";`;
          }
          return "";
        }
      },
    },
    {
      name: "@funstack/static:build",
      async buildApp(builder) {
        await buildApp(builder, this, { rscPayloadDir });
      },
    },
  ];
}