major: build islands + scan routeDir without importing user code (#3122)

This fixes a bunch of long standing issues in our tracker where a build
wouldn't finish because of importing user code. It's common for backend
apps to spawn some open ended tasks like subscribing to Deno KV or other
things. This addresses another problem of having to set up ENV vars just
for the build, even though they are technically not required to build
islands.

This also gives a roughly ~30% performance boost on cold starts (at
least on `deno.com`). Unfortunately, this does require some breaking
changes. But I believe the performance improvements + removing the
footgun of loading user code during build is well worth it. This work is
also a precursor in case we want to exploring moving to vite at some
point in the future.

## Breaking changes

1. Build options have moved to the builder.
```diff
  // main.ts
- const app = new App({ build: { outDir: "dist/" } })
+ const app = new App()

  // dev.ts
- const builder = new Builder();
+ const builder = new Builder({ outDir: "dist/" });
```

2. Another breaking change is how file based routes are loaded. Since
they're prepared and loaded by the builder the API changed.

```diff
  // main.ts
  const app = new App()
    .use(staticFiles())
  
- await fsRoutes(app, {
-   loadIsland: (path) => import(`./islands/${path}`),
-   loadRoute: (path) => import(`./routes/${path}`),
- }); 
+ app.fsRoutes()
```
You can optionally change the `islandDir` or `routeDir` by passing that
to the `Builder`:

```ts
// dev.ts
const builder = new Builder({
  islandDir: "/path/to/islands", 
  routeDir: "/path/to/routes"
});
```

3. Import `app` lazily in `dev.ts`. Passing `app` to `builder.build()`
is not necessary anymore.

```diff
- import { app } from "./main.ts";

  const builder = new Builder({ target: "safari12" });
  
  if (Deno.args.includes("build")) {
-    await builder.build(app);
+    await builder.build();
  } else {
-   await builder.listen(app);
+   await builder.listen(() => import("./main.ts"));
  }
```

4. The production run command has changed. It's now using `deno serve`
```diff
  // deno.json
  {
    "tasks": {
      "dev": "deno run -A --watch=static/,routes/ dev.ts",
      "dev": "deno run -A dev.ts build",
-     "start": "deno run -A main.ts",
+     "start": "deno serve -A _fresh/server.js",
    }
  }
```
Remove this bit in `main.ts`:

```diff
  // main.ts
  
- if (import.meta.main) {
-   await app.listen()
- }
```

Fixes #2240
Fixes #2640
Fixes #2592
Fixes #1843

Author: marvinhagemeister

.github/workflows/deploy.yml

@@ -22,7 +22,6 @@ jobs:
         uses: denoland/setup-deno@v2
         with:
           cache: true
-          deno-version: rc
 
       - name: Build step
         working-directory: ./www
@@ -32,5 +31,5 @@ jobs:
         uses: denoland/deployctl@v1
         with:
           project: "fresh"
-          entrypoint: "./www/main.ts"
+          entrypoint: "./www/_fresh/server.js"
           root: "."

deno.json

@@ -14,7 +14,8 @@
     ".": "./src/mod.ts",
     "./runtime": "./src/runtime/shared.ts",
     "./dev": "./src/dev/mod.ts",
-    "./compat": "./src/compat.ts"
+    "./compat": "./src/compat.ts",
+    "./do-not-use": "./src/internals.ts"
   },
   "tasks": {
     "test": "deno test -A --parallel",

docs/canary/deployment/production.md

@@ -29,7 +29,7 @@ To run Fresh in production mode, run the `start` task:
 ```sh Terminal
 deno task start
 # or
-deno run -A main.ts
+deno serve -A _fresh/server.js
 ```
 
 Fresh will automatically pick up the optimized assets in the `_fresh` directory.

docs/canary/examples/migration-guide.md

@@ -53,21 +53,20 @@ The full `dev.ts` file for newly generated Fresh 2 projects looks like this:
 ```ts
 import { Builder } from "fresh/dev";
 import { tailwind } from "@fresh/plugin-tailwind";
-import { app } from "./main.ts";
 
 // Pass development only configuration here
 const builder = new Builder({ target: "safari12" });
 
 // Example: Enabling the tailwind plugin for Fresh
-tailwind(builder, app);
+tailwind(builder);
 
 // Create optimized assets for the browser when
 // running `deno run -A dev.ts build`
 if (Deno.args.includes("build")) {
-  await builder.build(app);
+  await builder.build();
 } else {
   // ...otherwise start the development server
-  await builder.listen(app);
+  await builder.listen(() => import("./main.ts"));
 }
 ```
 
@@ -82,18 +81,9 @@ import { App, fsRoutes, staticFiles } from "fresh";
 
 export const app = new App()
   // Add static file serving middleware
-  .use(staticFiles());
-
-// Enable file-system based routing
-await fsRoutes(app, {
-  loadIsland: (path) => import(`./islands/${path}`),
-  loadRoute: (path) => import(`./routes/${path}`),
-});
-
-// If this module is called directly, start the server
-if (import.meta.main) {
-  await app.listen();
-}
+  .use(staticFiles())
+  // Enable file-system based routing
+  .fsRoutes();
 ```
 
 ## Merging error pages
@@ -226,9 +216,9 @@ Same is true for handlers:
 
 All the various context interfaces have been consolidated and simplified:
 
-| Fresh 1.x                                     | Fresh 2.x      |
-| --------------------------------------------- | -------------- |
-| `AppContext`, `LayoutContext`, `RouteContext` | `FreshContext` |
+| Fresh 1.x                                     | Fresh 2.x                                  |
+| --------------------------------------------- | ------------------------------------------ |
+| `AppContext`, `LayoutContext`, `RouteContext` | [`Context`](/docs/canary/concepts/context) |
 
 ### Context methods
 

examples/README.md

@@ -15,16 +15,6 @@ import { DemoIsland } from "jsr:@fresh/examples/island";
 export const app = new App({ root: import.meta.url })
   .use(staticFiles());
 
-// Register the island
-app.island(
-  // Module specifier for esbuild, could also be a file path
-  "jsr:@fresh/examples/island",
-  // Name of the island
-  "DemoIsland",
-  // Island component function
-  DemoIsland,
-);
-
 // Use the island somewhere in your components
 app.get("/", (ctx) => ctx.render(<DemoIsland />));
 

init/src/init.ts

@@ -158,11 +158,11 @@ ENV DENO_DEPLOYMENT_ID=\${GIT_REVISION}
 WORKDIR /app
 
 COPY . .
-RUN deno cache main.ts
+RUN deno cache _fresh/server.js
 
 EXPOSE 8000
 
-CMD ["run", "-A", "main.ts"]
+CMD ["serve", "-A", "_fresh/server.js"]
 
 `;
     await writeFile("Dockerfile", DOCKERFILE_TEXT);
@@ -349,7 +349,7 @@ ${GRADIENT_CSS}`;
     // Skip this and be silent if there is a network issue.
   }
 
-  const MAIN_TS = `import { App, fsRoutes, staticFiles } from "fresh";
+  const MAIN_TS = `import { App, staticFiles } from "fresh";
 import { define, type State } from "./utils.ts";
 
 export const app = new App<State>();
@@ -371,14 +371,8 @@ const exampleLoggerMiddleware = define.middleware((ctx) => {
 });
 app.use(exampleLoggerMiddleware);
 
-await fsRoutes(app, {
-  loadIsland: (path) => import(\`./islands/\${path}\`),
-  loadRoute: (path) => import(\`./routes/\${path}\`),
-});
-
-if (import.meta.main) {
-  await app.listen();
-}`;
+// Include file-system based routes here
+app.fsRoutes();`;
   await writeFile("main.ts", MAIN_TS);
 
   const COMPONENTS_BUTTON_TSX =
@@ -489,14 +483,13 @@ export default function Counter(props: CounterProps) {
   const DEV_TS = `#!/usr/bin/env -S deno run -A --watch=static/,routes/
 ${useTailwind ? `import { tailwind } from "@fresh/plugin-tailwind";\n` : ""}
 import { Builder } from "fresh/dev";
-import { app } from "./main.ts";
 
 const builder = new Builder();
-${useTailwind ? "tailwind(builder, app);" : ""}
+${useTailwind ? "tailwind(builder);" : ""}
 if (Deno.args.includes("build")) {
-  await builder.build(app);
+  await builder.build();
 } else {
-  await builder.listen(app);
+  await builder.listen(() => import("./main.ts"));
 }`;
   await writeFile("dev.ts", DEV_TS);
 
@@ -506,7 +499,7 @@ if (Deno.args.includes("build")) {
       check: "deno fmt --check . && deno lint . && deno check",
       dev: "deno run -A --watch=static/,routes/ dev.ts",
       build: "deno run -A dev.ts build",
-      start: "deno run -A main.ts",
+      start: "deno serve -A _fresh/server.js",
       update: "deno run -A -r jsr:@fresh/update .",
     },
     lint: {

init/src/init_test.ts

@@ -139,28 +139,31 @@ Deno.test({
   },
 });
 
-Deno.test("init with tailwind - fmt, lint, and type check project", async () => {
-  await using tmp = await withTmpDir();
-  const dir = tmp.dir;
-  using _promptStub = stubPrompt(".");
-  using _confirmStub = stubConfirm({
-    [CONFIRM_TAILWIND_MESSAGE]: true,
-  });
+Deno.test(
+  "init with tailwind - fmt, lint, and type check project",
+  async () => {
+    await using tmp = await withTmpDir();
+    const dir = tmp.dir;
+    using _promptStub = stubPrompt(".");
+    using _confirmStub = stubConfirm({
+      [CONFIRM_TAILWIND_MESSAGE]: true,
+    });
 
-  await initProject(dir, [], {});
-  await expectProjectFile(dir, "main.ts");
-  await expectProjectFile(dir, "dev.ts");
+    await initProject(dir, [], {});
+    await expectProjectFile(dir, "main.ts");
+    await expectProjectFile(dir, "dev.ts");
 
-  await patchProject(dir);
+    await patchProject(dir);
 
-  const check = await new Deno.Command(Deno.execPath(), {
-    args: ["task", "check"],
-    cwd: dir,
-    stderr: "inherit",
-    stdout: "inherit",
-  }).output();
-  expect(check.code).toEqual(0);
-});
+    const check = await new Deno.Command(Deno.execPath(), {
+      args: ["task", "check"],
+      cwd: dir,
+      stderr: "inherit",
+      stdout: "inherit",
+    }).output();
+    expect(check.code).toEqual(0);
+  },
+);
 
 Deno.test("init - can start dev server", async () => {
   await using tmp = await withTmpDir();
@@ -240,5 +243,5 @@ Deno.test("init - errors on missing build cache in prod", async () => {
   const { stderr } = getStdOutput(cp);
   expect(cp.code).toEqual(1);
 
-  expect(stderr).toMatch(/Found 1 islands, but did not/);
+  expect(stderr).toMatch(/Module not found/);
 });

plugin-tailwindcss/src/mod.ts

@@ -1,20 +1,18 @@
 import type { Builder } from "fresh/dev";
-import type { App } from "fresh";
 import twPostcss from "@tailwindcss/postcss";
 import postcss from "postcss";
 import type { TailwindPluginOptions } from "./types.ts";
 
 // Re-export types for public API
 export type { TailwindPluginOptions } from "./types.ts";
 
-export function tailwind<T>(
+export function tailwind(
   builder: Builder,
-  app: App<T>,
   options: TailwindPluginOptions = {},
 ): void {
   const { exclude, ...tailwindOptions } = options;
   const instance = postcss(twPostcss({
-    optimize: app.config.mode === "production",
+    optimize: builder.config.mode === "production",
     ...tailwindOptions,
   }));