@tanstack/start-plugin-core 1.121.0-alpha.8 → 1.121.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/start-plugin-core",
-  "version": "1.121.0-alpha.8",
+  "version": "1.121.0",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -58,16 +58,17 @@
     "babel-dead-code-elimination": "^1.0.9",
     "cheerio": "^1.0.0",
     "h3": "1.13.0",
-    "nitropack": "^2.11.8",
+    "nitropack": "^2.11.12",
     "pathe": "^2.0.3",
     "ufo": "^1.5.4",
     "xmlbuilder2": "^3.1.1",
     "zod": "^3.24.2",
-    "@tanstack/router-generator": "^1.121.0-alpha.5",
-    "@tanstack/router-core": "^1.121.0-alpha.5",
-    "@tanstack/router-utils": "^1.121.0-alpha.2",
-    "@tanstack/server-functions-plugin": "^1.121.0-alpha.8",
-    "@tanstack/router-plugin": "^1.121.0-alpha.5"
+    "@tanstack/router-core": "^1.121.0",
+    "@tanstack/router-generator": "^1.121.0",
+    "@tanstack/router-plugin": "^1.121.0",
+    "@tanstack/server-functions-plugin": "^1.121.0",
+    "@tanstack/router-utils": "^1.121.0",
+    "@tanstack/start-server-core": "^1.121.0"
   },
   "devDependencies": {
     "vite": "^6.0.0"

package/src/compilers.ts

@@ -25,17 +25,40 @@ export function compileStartOutputFactory(
       Program: {
         enter(programPath) {
           const identifiers: {
+            createServerRoute: IdentifierConfig
             createServerFileRoute: IdentifierConfig
             createServerFn: IdentifierConfig
             createMiddleware: IdentifierConfig
             serverOnly: IdentifierConfig
             clientOnly: IdentifierConfig
             createIsomorphicFn: IdentifierConfig
+            createServerRootRoute: IdentifierConfig
           } = {
+            createServerRootRoute: {
+              name: 'createServerRootRoute',
+              handleCallExpression:
+                handleCreateServerFileRouteCallExpressionFactory(
+                  framework,
+                  'createServerRootRoute',
+                ),
+              paths: [],
+            },
+            createServerRoute: {
+              name: 'createServerRoute',
+              handleCallExpression:
+                handleCreateServerFileRouteCallExpressionFactory(
+                  framework,
+                  'createServerRoute',
+                ),
+              paths: [],
+            },
             createServerFileRoute: {
               name: 'createServerFileRoute',
               handleCallExpression:
-                handleCreateServerFileRouteCallExpressionFactory(framework),
+                handleCreateServerFileRouteCallExpressionFactory(
+                  framework,
+                  'createServerFileRoute',
+                ),
               paths: [],
             },
             createServerFn: {
@@ -71,10 +94,7 @@ export function compileStartOutputFactory(
 
           programPath.traverse({
             ImportDeclaration: (path) => {
-              if (
-                path.node.source.value !== '@tanstack/react-start' &&
-                path.node.source.value !== '@tanstack/solid-start'
-              ) {
+              if (path.node.source.value !== `@tanstack/${framework}-start`) {
                 return
               }
 
@@ -169,6 +189,10 @@ export function compileStartOutputFactory(
 
 function handleCreateServerFileRouteCallExpressionFactory(
   factory: CompileStartFrameworkOptions,
+  method:
+    | 'createServerFileRoute'
+    | 'createServerRoute'
+    | 'createServerRootRoute',
 ) {
   return function handleCreateServerFileRouteCallExpression(
     path: babel.NodePath<t.CallExpression>,
@@ -184,95 +208,6 @@ function handleCreateServerFileRouteCallExpressionFactory(
 
     const programPath = highestParent.parentPath as babel.NodePath<t.Program>
 
-    // // Find the root call expression and all of the methods that are called on it
-    // const rootCallExpression = getRootCallExpression(path)
-
-    // const callExpressionPaths = {
-    //   validator: null as babel.NodePath<t.CallExpression> | null,
-    //   middleware: null as babel.NodePath<t.CallExpression> | null,
-    //   methods: null as babel.NodePath<t.CallExpression> | null,
-    // }
-
-    // const validMethods = Object.keys(callExpressionPaths)
-
-    // rootCallExpression.traverse({
-    //   MemberExpression(memberExpressionPath) {
-    //     if (t.isIdentifier(memberExpressionPath.node.property)) {
-    //       const name = memberExpressionPath.node.property
-    //         .name as keyof typeof callExpressionPaths
-
-    //       if (
-    //         validMethods.includes(name) &&
-    //         memberExpressionPath.parentPath.isCallExpression()
-    //       ) {
-    //         callExpressionPaths[name] = memberExpressionPath.parentPath
-    //       }
-    //     }
-    //   },
-    // })
-
-    // const manifest = { middleware: false, methods: {} as any }
-
-    // Object.entries(callExpressionPaths).forEach(([key, callPath]) => {
-    //   if (callPath && t.isMemberExpression(callPath.node.callee)) {
-    //     if (key === 'middleware') {
-    //       manifest.middleware = true
-    //     } else if (key === 'methods') {
-    //       // Get the methods object from the methods call
-    //       const methodsArg = callPath.node.arguments[0]
-
-    //       // Handle the case where methods is a function that returns an object
-    //       if (
-    //         t.isArrowFunctionExpression(methodsArg) &&
-    //         t.isObjectExpression(methodsArg.body)
-    //       ) {
-    //         methodsArg.body.properties.forEach((prop) => {
-    //           if (t.isObjectProperty(prop) && t.isIdentifier(prop.key)) {
-    //             const methodName = prop.key.name
-    //             manifest.methods[methodName] = {
-    //               middleware: false,
-    //             }
-
-    //             // Check if this method has a middleware
-    //             if (t.isCallExpression(prop.value)) {
-    //               const method = prop.value
-    //               method.arguments.forEach((arg) => {
-    //                 if (t.isObjectExpression(arg)) {
-    //                   arg.properties.forEach((methodProp) => {
-    //                     if (
-    //                       t.isObjectProperty(methodProp) &&
-    //                       t.isIdentifier(methodProp.key)
-    //                     ) {
-    //                       if (methodProp.key.name === 'middleware') {
-    //                         manifest.methods[methodName].middleware = true
-    //                       }
-    //                     }
-    //                   })
-    //                 }
-    //               })
-    //             }
-    //           }
-    //         })
-    //       }
-    //       // Handle the case where methods is a direct object
-    //       else if (t.isObjectExpression(methodsArg)) {
-    //         methodsArg.properties.forEach((prop) => {
-    //           if (t.isObjectProperty(prop) && t.isIdentifier(prop.key)) {
-    //             const methodName = prop.key.name
-    //             manifest.methods[methodName] = {
-    //               middleware: false,
-    //             }
-    //           }
-    //         })
-    //       }
-    //     }
-
-    //     if (opts.env === 'client') {
-    //       callPath.replaceWith(callPath.node.callee.object)
-    //     }
-    //   }
-    // })
-
     // If we're on the client, remove the entire variable
     if (opts.env === 'client') {
       // console.debug('createServerFileRoute -> manifest:\n', manifest)
@@ -280,36 +215,6 @@ function handleCreateServerFileRouteCallExpressionFactory(
       return
     }
 
-    // path.replaceWith(
-    //   t.callExpression(t.identifier('createServerFileRoute'), [
-    //     t.identifier('undefined'),
-    //     t.callExpression(
-    //       t.memberExpression(t.identifier('Object'), t.identifier('assign')),
-    //       [
-    //         t.objectExpression(
-    //           path.node.arguments
-    //             .map((arg) => {
-    //               if (t.isIdentifier(arg)) {
-    //                 return t.objectProperty(t.identifier(arg.name), arg)
-    //               }
-    //               // Handle other cases or return a default value if necessary
-    //               return null // or throw an error, or handle accordingly
-    //             })
-    //             .filter(
-    //               (property): property is t.ObjectProperty => property !== null,
-    //             ),
-    //         ),
-    //         t.objectExpression([
-    //           t.objectProperty(
-    //             t.identifier('manifest'),
-    //             t.valueToNode(manifest),
-    //           ),
-    //         ]),
-    //       ],
-    //     ),
-    //   ]),
-    // )
-
     let isCreateServerFileRouteImported = false as boolean
 
     programPath.traverse({
@@ -321,7 +226,7 @@ function handleCreateServerFileRouteCallExpressionFactory(
             return (
               t.isImportSpecifier(specifier) &&
               t.isIdentifier(specifier.imported) &&
-              specifier.imported.name === 'createServerFileRoute'
+              specifier.imported.name === method
             )
           })
         }
@@ -330,12 +235,7 @@ function handleCreateServerFileRouteCallExpressionFactory(
 
     if (!isCreateServerFileRouteImported) {
       const importDeclaration = t.importDeclaration(
-        [
-          t.importSpecifier(
-            t.identifier('createServerFileRoute'),
-            t.identifier('createServerFileRoute'),
-          ),
-        ],
+        [t.importSpecifier(t.identifier(method), t.identifier(method))],
         t.stringLiteral(PACKAGES.start),
       )
       programPath.node.body.unshift(importDeclaration)

package/src/constants.ts

@@ -1,6 +1,16 @@
+import path from 'node:path'
+
 export const VITE_ENVIRONMENT_NAMES = {
   // 'ssr' is chosen as the name for the server environment to ensure backwards compatibility
   // with vite plugins that are not compatible with the new vite environment API (e.g. tailwindcss)
   server: 'ssr',
   client: 'client',
 } as const
+
+export const CLIENT_DIST_DIR = path.join(
+  '.tanstack',
+  'start',
+  'build',
+  'client-dist',
+)
+export const SSR_ENTRY_FILE = 'ssr.mjs'

package/src/debug.ts

@@ -0,0 +1,3 @@
+export const debug =
+  process.env.TSR_VITE_DEBUG &&
+  ['true', 'start-plugin-core'].includes(process.env.TSR_VITE_DEBUG)

package/src/{nitro/dev-server-plugin.ts → dev-server-plugin/plugin.ts}

@@ -1,7 +1,7 @@
 import { createEvent, getHeader, sendWebResponse } from 'h3'
 import { isRunnableDevEnvironment } from 'vite'
-import { extractHtmlScripts } from '../extractHtmlScripts'
 import { VITE_ENVIRONMENT_NAMES } from '../constants'
+import { extractHtmlScripts } from './extract-html-scripts'
 import type { Connect, DevEnvironment, Plugin, ViteDevServer } from 'vite'
 
 declare global {
@@ -29,8 +29,12 @@ export function devServerPlugin(): Plugin {
       return () => {
         remove_html_middlewares(viteDevServer.middlewares)
         let cachedScripts: string | undefined
+
         viteDevServer.middlewares.use(async (req, res) => {
+          // Create an H3Event to have it passed into the server entry
+          // i.e: event => defineEventHandler(event)
           const event = createEvent(req, res)
+
           const serverEnv = viteDevServer.environments[
             VITE_ENVIRONMENT_NAMES.server
           ] as DevEnvironment | undefined
@@ -41,11 +45,14 @@ export function devServerPlugin(): Plugin {
                 `Server environment ${VITE_ENVIRONMENT_NAMES.server} not found`,
               )
             }
+
             if (!isRunnableDevEnvironment(serverEnv)) {
               throw new Error(
                 `Expected server environment ${VITE_ENVIRONMENT_NAMES.server} to be a RunnableDevEnvironment. This can be caused by multiple vite versions being installed in the project.`,
               )
             }
+
+            // Extract the scripts that Vite plugins would inject into the initial HTML
             if (cachedScripts === undefined) {
               const templateHtml = `<html><head></head><body></body></html>`
               const transformedHtml = await viteDevServer.transformIndexHtml(
@@ -57,6 +64,9 @@ export function devServerPlugin(): Plugin {
                 .map((script) => script.content ?? '')
                 .join(';')
             }
+
+            // Import and resolve the request by running the server entry point
+            // i.e export default defineEventHandler((event) => { ... })
             const serverEntry = await serverEnv.runner.import(
               '/~start/server-entry',
             )

package/src/global.d.ts

@@ -0,0 +1,8 @@
+import type { Manifest } from '@tanstack/router-core'
+
+/* eslint-disable no-var */
+declare global {
+  var TSS_APP_BASE: string
+  var TSS_ROUTES_MANIFEST: Manifest
+}
+export {}

package/src/load-env-plugin/plugin.ts

@@ -0,0 +1,17 @@
+import * as vite from 'vite'
+import type { TanStackStartOutputConfig } from '../plugin'
+
+export function loadEnvPlugin(
+  startOpts: TanStackStartOutputConfig,
+): vite.Plugin {
+  return {
+    name: 'tanstack-vite-plugin-nitro-load-env',
+    enforce: 'pre',
+    config(userConfig, envConfig) {
+      Object.assign(
+        process.env,
+        vite.loadEnv(envConfig.mode, userConfig.root ?? startOpts.root, ''),
+      )
+    },
+  }
+}

package/src/{build-sitemap.ts → nitro-plugin/build-sitemap.ts}

@@ -1,7 +1,8 @@
 import { writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { create } from 'xmlbuilder2'
-import type { TanStackStartOutputConfig } from './plugin'
+import { createLogger } from '../utils'
+import type { TanStackStartOutputConfig } from '../plugin'
 import type { XMLBuilder } from 'xmlbuilder2/lib/interfaces'
 
 export type SitemapUrl = {
@@ -121,13 +122,15 @@ function jsonToXml(sitemapData: SitemapData): string {
   return sitemap.end({ prettyPrint: true })
 }
 
-export async function buildSitemap({
+export function buildSitemap({
   options,
   publicDir,
 }: {
   options: TanStackStartOutputConfig
   publicDir: string
 }) {
+  const logger = createLogger('sitemap')
+
   let sitemapOptions = options.sitemap
 
   if (!sitemapOptions && options.pages.length) {
@@ -142,7 +145,7 @@ export async function buildSitemap({
 
   if (!host) {
     if (!options.sitemap) {
-      console.info(
+      logger.info(
         'Hint: Pages found, but no sitemap host has been set. To enable sitemap generation, set the `sitemap.host` option.',
       )
       return
@@ -159,11 +162,11 @@ export async function buildSitemap({
   const { pages } = options
 
   if (!pages.length) {
-    console.log('No pages were found to build the sitemap. Skipping...')
+    logger.info('No pages were found to build the sitemap. Skipping...')
     return
   }
 
-  console.log('Building Sitemap...')
+  logger.info('Building Sitemap...')
 
   // Build the sitemap data
   const sitemapData = buildSitemapJson(pages, host)
@@ -174,11 +177,11 @@ export async function buildSitemap({
 
   try {
     // Write XML sitemap
-    console.log(`Writing sitemap XML at ${xmlOutputPath}`)
+    logger.info(`Writing sitemap XML at ${xmlOutputPath}`)
     writeFileSync(xmlOutputPath, jsonToXml(sitemapData))
 
     // Write pages data for runtime use
-    console.log(`Writing pages data at ${pagesOutputPath}`)
+    logger.info(`Writing pages data at ${pagesOutputPath}`)
     writeFileSync(
       pagesOutputPath,
       JSON.stringify(
@@ -192,7 +195,7 @@ export async function buildSitemap({
       ),
     )
   } catch (e) {
-    console.error(`Unable to write sitemap files`, e)
+    logger.error(`Unable to write sitemap files`, e)
   }
 }
 

package/src/nitro-plugin/plugin.ts

@@ -0,0 +1,244 @@
+import path from 'node:path'
+import { rmSync } from 'node:fs'
+import { build, copyPublicAssets, createNitro, prepare } from 'nitropack'
+import { dirname, resolve } from 'pathe'
+import {
+  CLIENT_DIST_DIR,
+  SSR_ENTRY_FILE,
+  VITE_ENVIRONMENT_NAMES,
+} from '../constants'
+import { buildSitemap } from './build-sitemap'
+import { prerender } from './prerender'
+import type {
+  EnvironmentOptions,
+  PluginOption,
+  Rollup,
+  ViteBuilder,
+} from 'vite'
+import type { Nitro, NitroConfig } from 'nitropack'
+import type { TanStackStartOutputConfig } from '../plugin'
+
+export function nitroPlugin(
+  options: TanStackStartOutputConfig,
+  getSsrBundle: () => Rollup.OutputBundle,
+): Array<PluginOption> {
+  const buildPreset =
+    process.env['START_TARGET'] ?? (options.target as string | undefined)
+  return [
+    {
+      name: 'tanstack-vite-plugin-nitro',
+      configEnvironment(name) {
+        if (name === VITE_ENVIRONMENT_NAMES.server) {
+          return {
+            build: {
+              commonjsOptions: {
+                include: [],
+              },
+              ssr: true,
+              sourcemap: true,
+              rollupOptions: {
+                input: '/~start/server-entry',
+              },
+            },
+          } satisfies EnvironmentOptions
+        }
+
+        return null
+      },
+      config() {
+        return {
+          builder: {
+            sharedPlugins: true,
+            async buildApp(builder) {
+              const client = builder.environments[VITE_ENVIRONMENT_NAMES.client]
+              const server = builder.environments[VITE_ENVIRONMENT_NAMES.server]
+
+              if (!client) {
+                throw new Error('Client environment not found')
+              }
+
+              if (!server) {
+                throw new Error('SSR environment not found')
+              }
+
+              // Build the client bundle
+              // i.e client entry file with `hydrateRoot(...)`
+              const clientOutputDir = resolve(options.root, CLIENT_DIST_DIR)
+              rmSync(clientOutputDir, { recursive: true, force: true })
+              await builder.build(client)
+
+              // Build the SSR bundle
+              await builder.build(server)
+
+              const nitroConfig: NitroConfig = {
+                dev: false,
+                // TODO: do we need this? should this be made configurable?
+                compatibilityDate: '2024-11-19',
+                logLevel: 3,
+                preset: buildPreset,
+                baseURL: globalThis.TSS_APP_BASE,
+                publicAssets: [
+                  {
+                    dir: path.resolve(options.root, CLIENT_DIST_DIR),
+                    baseURL: '/',
+                    maxAge: 31536000, // 1 year
+                  },
+                ],
+                typescript: {
+                  generateTsConfig: false,
+                },
+                prerender: undefined,
+                renderer: SSR_ENTRY_FILE,
+                plugins: [], // Nitro's plugins
+                appConfigFiles: [],
+                scanDirs: [],
+                imports: false, // unjs/unimport for global/magic imports
+                rollupConfig: {
+                  plugins: [virtualBundlePlugin(getSsrBundle())],
+                },
+                virtual: {
+                  // This is Nitro's way of defining virtual modules
+                  // Should we define the ones for TanStack Start's here as well?
+                },
+              }
+
+              const nitro = await createNitro(nitroConfig)
+
+              await buildNitroApp(builder, nitro, options)
+            },
+          },
+        }
+      },
+    },
+  ]
+}
+
+/**
+ * Correctly co-ordinates the nitro app build process to make sure that the
+ * app is built, while also correctly handling the prerendering and sitemap
+ * generation and including their outputs in the final build.
+ */
+async function buildNitroApp(
+  builder: ViteBuilder,
+  nitro: Nitro,
+  options: TanStackStartOutputConfig,
+) {
+  // Cleans the public and server directories for a fresh build
+  // i.e the `.output/public` and `.output/server` directories
+  await prepare(nitro)
+
+  // Creates the `.output/public` directory and copies the public assets
+  await copyPublicAssets(nitro)
+
+  // If the user has not set a prerender option, we need to set it to true
+  // if the pages array is not empty and has sub options requiring for prerendering
+  if (options.prerender?.enabled !== false) {
+    options.prerender = {
+      ...options.prerender,
+      enabled: options.pages.some((d) =>
+        typeof d === 'string' ? false : !!d.prerender?.enabled,
+      ),
+    }
+  }
+
+  // Setup the options for prerendering the SPA shell (i.e `src/routes/__root.tsx`)
+  if (options.spa?.enabled) {
+    options.prerender = {
+      ...options.prerender,
+      enabled: true,
+    }
+
+    const maskUrl = new URL(options.spa.maskPath, 'http://localhost')
+
+    maskUrl.searchParams.set('__TSS_SHELL', 'true')
+
+    options.pages.push({
+      path: maskUrl.toString().replace('http://localhost', ''),
+      prerender: options.spa.prerender,
+      sitemap: {
+        exclude: true,
+      },
+    })
+  }
+
+  // Run the prerendering process
+  if (options.prerender.enabled) {
+    await prerender({
+      options,
+      nitro,
+      builder,
+    })
+  }
+
+  // Run the sitemap build process
+  if (options.pages.length) {
+    buildSitemap({
+      options,
+      publicDir: nitro.options.output.publicDir,
+    })
+  }
+
+  // Build the nitro app
+  // We only build the nitro app, once we've prepared the public assets,
+  // prerendered the pages and built the sitemap.
+  // If we try to do this earlier, then the public assets may not be available
+  // in the production build.
+  await build(nitro)
+
+  // Close the nitro instance
+  await nitro.close()
+  nitro.logger.success(
+    'Client and Server bundles for TanStack Start have been successfully built.',
+  )
+}
+
+type NitroRollupPluginOption = NonNullable<
+  NitroConfig['rollupConfig']
+>['plugins']
+
+function virtualBundlePlugin(
+  ssrBundle: Rollup.OutputBundle,
+): NitroRollupPluginOption {
+  type VirtualModule = { code: string; map: string | null }
+  const _modules = new Map<string, VirtualModule>()
+
+  // group chunks and source maps
+  for (const [fileName, content] of Object.entries(ssrBundle)) {
+    if (content.type === 'chunk') {
+      const virtualModule: VirtualModule = {
+        code: content.code,
+        map: null,
+      }
+      const maybeMap = ssrBundle[`${fileName}.map`]
+      if (maybeMap && maybeMap.type === 'asset') {
+        virtualModule.map = maybeMap.source as string
+      }
+      _modules.set(fileName, virtualModule)
+      _modules.set(resolve(fileName), virtualModule)
+    }
+  }
+
+  return {
+    name: 'virtual-bundle',
+    resolveId(id, importer) {
+      if (_modules.has(id)) {
+        return resolve(id)
+      }
+
+      if (importer) {
+        const resolved = resolve(dirname(importer), id)
+        if (_modules.has(resolved)) {
+          return resolved
+        }
+      }
+      return null
+    },
+    load(id) {
+      const m = _modules.get(id)
+      if (!m) {
+        return null
+      }
+      return m
+    },
+  }
+}