@tanstack/start-plugin-core 1.121.0-alpha.2 → 1.121.0-alpha.21

package/dist/esm/utils.js

@@ -0,0 +1,18 @@
+function resolveViteId(id) {
+  return `\0${id}`;
+}
+function createLogger(prefix) {
+  const label = `[${prefix}]`;
+  return {
+    log: (...args) => console.log(label, ...args),
+    debug: (...args) => console.debug(label, ...args),
+    info: (...args) => console.info(label, ...args),
+    warn: (...args) => console.warn(label, ...args),
+    error: (...args) => console.error(label, ...args)
+  };
+}
+export {
+  createLogger,
+  resolveViteId
+};
+//# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["export function resolveViteId(id: string) {\n  return `\\0${id}`\n}\n\nexport function createLogger(prefix: string) {\n  const label = `[${prefix}]`\n  return {\n    log: (...args: any) => console.log(label, ...args),\n    debug: (...args: any) => console.debug(label, ...args),\n    info: (...args: any) => console.info(label, ...args),\n    warn: (...args: any) => console.warn(label, ...args),\n    error: (...args: any) => console.error(label, ...args),\n  }\n}\n"],"names":[],"mappings":"AAAO,SAAS,cAAc,IAAY;AACxC,SAAO,KAAK,EAAE;AAChB;AAEO,SAAS,aAAa,QAAgB;AACrC,QAAA,QAAQ,IAAI,MAAM;AACjB,SAAA;AAAA,IACL,KAAK,IAAI,SAAc,QAAQ,IAAI,OAAO,GAAG,IAAI;AAAA,IACjD,OAAO,IAAI,SAAc,QAAQ,MAAM,OAAO,GAAG,IAAI;AAAA,IACrD,MAAM,IAAI,SAAc,QAAQ,KAAK,OAAO,GAAG,IAAI;AAAA,IACnD,MAAM,IAAI,SAAc,QAAQ,KAAK,OAAO,GAAG,IAAI;AAAA,IACnD,OAAO,IAAI,SAAc,QAAQ,MAAM,OAAO,GAAG,IAAI;AAAA,EACvD;AACF;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/start-plugin-core",
-  "version": "1.121.0-alpha.2",
+  "version": "1.121.0-alpha.21",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -58,16 +58,16 @@
     "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-core": "^1.121.0-alpha.1",
-    "@tanstack/router-generator": "^1.121.0-alpha.1",
-    "@tanstack/router-plugin": "^1.121.0-alpha.2",
+    "@tanstack/router-core": "^1.121.0-alpha.14",
+    "@tanstack/router-generator": "^1.121.0-alpha.14",
     "@tanstack/router-utils": "^1.121.0-alpha.2",
-    "@tanstack/server-functions-plugin": "^1.121.0-alpha.2"
+    "@tanstack/server-functions-plugin": "^1.121.0-alpha.8",
+    "@tanstack/router-plugin": "^1.121.0-alpha.14"
   },
   "devDependencies": {
     "vite": "^6.0.0"

package/src/constants.ts

@@ -4,3 +4,6 @@ export const VITE_ENVIRONMENT_NAMES = {
   server: 'ssr',
   client: 'client',
 } as const
+
+export const CLIENT_DIST_DIR = '.tanstack-start/build/client-dist'
+export const SSR_ENTRY_FILE = 'ssr.mjs'

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/index.ts

@@ -5,3 +5,4 @@ export {
 } from './schema'
 
 export { TanStackStartVitePluginCore } from './plugin'
+export { resolveViteId } from './utils'

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/nitro-plugin/build-sitemap.ts

@@ -0,0 +1,213 @@
+import { writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { create } from 'xmlbuilder2'
+import { createLogger } from '../utils'
+import type { TanStackStartOutputConfig } from '../plugin'
+import type { XMLBuilder } from 'xmlbuilder2/lib/interfaces'
+
+export type SitemapUrl = {
+  loc: string
+  lastmod: string
+  priority?: number
+  changefreq?:
+    | 'always'
+    | 'hourly'
+    | 'daily'
+    | 'weekly'
+    | 'monthly'
+    | 'yearly'
+    | 'never'
+  alternateRefs?: Array<{
+    href: string
+    hreflang?: string
+  }>
+  images?: Array<{
+    loc: string
+    title?: string
+    caption?: string
+  }>
+  news?: {
+    publication: {
+      name: string
+      language: string
+    }
+    publicationDate: string | Date
+    title: string
+  }
+}
+
+export type SitemapData = {
+  urls: Array<SitemapUrl>
+}
+
+function buildSitemapJson(
+  pages: TanStackStartOutputConfig['pages'],
+  host: string,
+): SitemapData {
+  const slash = checkSlash(host)
+
+  const urls: Array<SitemapUrl> = pages
+    .filter((page) => {
+      return page.sitemap?.exclude !== true
+    })
+    .map((page) => ({
+      loc: `${host}${slash}${page.path.replace(/^\/+/g, '')}`,
+      lastmod: page.sitemap?.lastmod
+        ? new Date(page.sitemap.lastmod).toISOString().split('T')[0]!
+        : new Date().toISOString().split('T')[0]!,
+      priority: page.sitemap?.priority,
+      changefreq: page.sitemap?.changefreq,
+      alternateRefs: page.sitemap?.alternateRefs,
+      images: page.sitemap?.images,
+      news: page.sitemap?.news,
+    }))
+
+  return { urls }
+}
+
+function jsonToXml(sitemapData: SitemapData): string {
+  const sitemap = createXml('urlset')
+
+  for (const item of sitemapData.urls) {
+    const page = sitemap.ele('url')
+    page.ele('loc').txt(item.loc)
+    page.ele('lastmod').txt(item.lastmod)
+
+    if (item.priority !== undefined) {
+      page.ele('priority').txt(item.priority.toString())
+    }
+    if (item.changefreq) {
+      page.ele('changefreq').txt(item.changefreq)
+    }
+
+    // Add alternate references
+    if (item.alternateRefs?.length) {
+      for (const ref of item.alternateRefs) {
+        const alternateRef = page.ele('xhtml:link')
+        alternateRef.att('rel', 'alternate')
+        alternateRef.att('href', ref.href)
+        if (ref.hreflang) {
+          alternateRef.att('hreflang', ref.hreflang)
+        }
+      }
+    }
+
+    // Add images
+    if (item.images?.length) {
+      for (const image of item.images) {
+        const imageElement = page.ele('image:image')
+        imageElement.ele('image:loc').txt(image.loc)
+        if (image.title) {
+          imageElement.ele('image:title').txt(image.title)
+        }
+        if (image.caption) {
+          imageElement.ele('image:caption').txt(image.caption)
+        }
+      }
+    }
+
+    // Add news
+    if (item.news) {
+      const newsElement = page.ele('news:news')
+      const publication = newsElement.ele('news:publication')
+      publication.ele('news:name').txt(item.news.publication.name)
+      publication.ele('news:language').txt(item.news.publication.language)
+      newsElement
+        .ele('news:publication_date')
+        .txt(new Date(item.news.publicationDate).toISOString().split('T')[0]!)
+      newsElement.ele('news:title').txt(item.news.title)
+    }
+  }
+
+  return sitemap.end({ prettyPrint: true })
+}
+
+export function buildSitemap({
+  options,
+  publicDir,
+}: {
+  options: TanStackStartOutputConfig
+  publicDir: string
+}) {
+  const logger = createLogger('sitemap')
+
+  let sitemapOptions = options.sitemap
+
+  if (!sitemapOptions && options.pages.length) {
+    sitemapOptions = { enabled: true, outputPath: 'sitemap.xml' }
+  }
+
+  if (!sitemapOptions?.enabled) {
+    throw new Error('Sitemap is not enabled')
+  }
+
+  const { host, outputPath } = sitemapOptions
+
+  if (!host) {
+    if (!options.sitemap) {
+      logger.info(
+        'Hint: Pages found, but no sitemap host has been set. To enable sitemap generation, set the `sitemap.host` option.',
+      )
+      return
+    }
+    throw new Error(
+      'Sitemap host is not set and required to build the sitemap.',
+    )
+  }
+
+  if (!outputPath) {
+    throw new Error('Sitemap output path is not set')
+  }
+
+  const { pages } = options
+
+  if (!pages.length) {
+    logger.info('No pages were found to build the sitemap. Skipping...')
+    return
+  }
+
+  logger.info('Building Sitemap...')
+
+  // Build the sitemap data
+  const sitemapData = buildSitemapJson(pages, host)
+
+  // Generate output paths
+  const xmlOutputPath = path.join(publicDir, outputPath)
+  const pagesOutputPath = path.join(publicDir, 'pages.json')
+
+  try {
+    // Write XML sitemap
+    logger.info(`Writing sitemap XML at ${xmlOutputPath}`)
+    writeFileSync(xmlOutputPath, jsonToXml(sitemapData))
+
+    // Write pages data for runtime use
+    logger.info(`Writing pages data at ${pagesOutputPath}`)
+    writeFileSync(
+      pagesOutputPath,
+      JSON.stringify(
+        {
+          pages,
+          host,
+          lastBuilt: new Date().toISOString(),
+        },
+        null,
+        2,
+      ),
+    )
+  } catch (e) {
+    logger.error(`Unable to write sitemap files`, e)
+  }
+}
+
+function createXml(elementName: 'urlset' | 'sitemapindex'): XMLBuilder {
+  return create({ version: '1.0', encoding: 'UTF-8' })
+    .ele(elementName, {
+      xmlns: 'https://www.sitemaps.org/schemas/sitemap/0.9',
+    })
+    .com(`This file was automatically generated by TanStack Start.`)
+}
+
+function checkSlash(host: string): string {
+  const finalChar = host.slice(-1)
+  return finalChar === '/' ? '' : '/'
+}

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
+    },
+  }
+}

package/src/{prerender.ts → nitro-plugin/prerender.ts}

@@ -4,13 +4,13 @@ import path from 'node:path'
 import { getRollupConfig } from 'nitropack/rollup'
 import { build as buildNitro, createNitro } from 'nitropack'
 import { joinURL, withBase, withoutBase } from 'ufo'
+import { VITE_ENVIRONMENT_NAMES } from '../constants'
+import { createLogger } from '../utils'
 import { Queue } from './queue'
-import { buildNitroEnvironment } from './nitro/build-nitro'
-import { VITE_ENVIRONMENT_NAMES } from './constants'
 import type { ViteBuilder } from 'vite'
 import type { $Fetch, Nitro } from 'nitropack'
-import type { TanStackStartOutputConfig } from './plugin'
-import type { Page } from './schema'
+import type { TanStackStartOutputConfig } from '../plugin'
+import type { Page } from '../schema'
 
 export async function prerender({
   options,
@@ -21,7 +21,8 @@ export async function prerender({
   nitro: Nitro
   builder: ViteBuilder
 }) {
-  console.info('Prendering pages...')
+  const logger = createLogger('prerender')
+  logger.info('Prendering pages...')
 
   // If prerender is enabled but no pages are provided, default to prerendering the root page
   if (options.prerender?.enabled && !options.pages.length) {
@@ -72,7 +73,7 @@ export async function prerender({
     },
   }
 
-  await buildNitroEnvironment(nodeNitro, () => buildNitro(nodeNitro))
+  await buildNitro(nodeNitro)
 
   // Import renderer entry
   const serverFilename =
@@ -93,14 +94,14 @@ export async function prerender({
     // Crawl all pages
     const pages = await prerenderPages()
 
-    console.info(`Prerendered ${pages.length} pages:`)
+    logger.info(`Prerendered ${pages.length} pages:`)
     pages.forEach((page) => {
-      console.info(`- ${page}`)
+      logger.info(`- ${page}`)
     })
 
     // TODO: Write the prerendered pages to the output directory
   } catch (error) {
-    console.error(error)
+    logger.error(error)
   } finally {
     // Ensure server is always closed
     // server.process.kill()
@@ -126,18 +127,10 @@ export async function prerender({
     const seen = new Set<string>()
     const retriesByPath = new Map<string, number>()
     const concurrency = options.prerender?.concurrency ?? os.cpus().length
-    console.info(`Concurrency: ${concurrency}`)
+    logger.info(`Concurrency: ${concurrency}`)
     const queue = new Queue({ concurrency })
 
-    options.pages.forEach((_page) => {
-      let page = _page as Page
-
-      if (typeof _page === 'string') {
-        page = { path: _page }
-      }
-
-      addCrawlPageTask(page)
-    })
+    options.pages.forEach((page) => addCrawlPageTask(page))
 
     await queue.start()
 
@@ -168,7 +161,7 @@ export async function prerender({
 
       // Add the task
       queue.add(async () => {
-        console.info(`Crawling: ${page.path}`)
+        logger.info(`Crawling: ${page.path}`)
         const retries = retriesByPath.get(page.path) || 0
         try {
           // Fetch the route
@@ -236,7 +229,7 @@ export async function prerender({
           }
         } catch (error) {
           if (retries < (prerenderOptions.retryCount ?? 0)) {
-            console.warn(`Encountered error, retrying: ${page.path} in 500ms`)
+            logger.warn(`Encountered error, retrying: ${page.path} in 500ms`)
             await new Promise((resolve) =>
               setTimeout(resolve, prerenderOptions.retryDelay),
             )