fix: wait for async loaders before executing head functions

e2e/solid-start/basic-head/.gitignore

@@ -0,0 +1 @@
+/test-results/

e2e/solid-start/basic-head/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "tanstack-solid-start-e2e-basic-head",
+  "private": true,
+  "sideEffects": false,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "dev:e2e": "vite dev",
+    "build": "vite build && tsc --noEmit",
+    "build:spa": "MODE=spa vite build && tsc --noEmit",
+    "build:prerender": "MODE=prerender vite build && tsc --noEmit",
+    "preview": "vite preview",
+    "start": "pnpm exec srvx --prod -s ../client dist/server/server.js",
+    "start:spa": "node server.js",
+    "test:e2e:startDummyServer": "node -e 'import(\"./tests/setup/global.setup.ts\").then(m => m.default())' &",
+    "test:e2e:stopDummyServer": "node -e 'import(\"./tests/setup/global.teardown.ts\").then(m => m.default())'",
+    "test:e2e:spaMode": "rm -rf port*.txt; MODE=spa playwright test --project=chromium",
+    "test:e2e:ssrMode": "rm -rf port*.txt; playwright test --project=chromium",
+    "test:e2e:prerender": "rm -rf port*.txt; MODE=prerender playwright test --project=chromium",
+    "test:e2e:preview": "rm -rf port*.txt; MODE=preview playwright test --project=chromium",
+    "test:e2e": "pnpm run test:e2e:spaMode && pnpm run test:e2e:ssrMode && pnpm run test:e2e:prerender && pnpm run test:e2e:preview"
+  },
+  "dependencies": {
+    "@tanstack/solid-router": "workspace:^",
+    "@tanstack/solid-router-devtools": "workspace:^",
+    "@tanstack/solid-start": "workspace:^",
+    "express": "^5.1.0",
+    "http-proxy-middleware": "^3.0.5",
+    "solid-js": "^1.9.10",
+    "vite": "^7.1.7"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.50.1",
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/router-e2e-utils": "workspace:^",
+    "@types/node": "^22.10.2",
+    "srvx": "^0.9.8",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.7.2",
+    "vite-plugin-solid": "^2.11.10",
+    "vite-tsconfig-paths": "^5.1.4"
+  }
+}

e2e/solid-start/basic-head/playwright.config.ts

@@ -0,0 +1,72 @@
+import { defineConfig, devices } from '@playwright/test'
+import {
+  getDummyServerPort,
+  getTestServerPort,
+} from '@tanstack/router-e2e-utils'
+import { isSpaMode } from './tests/utils/isSpaMode'
+import { isPrerender } from './tests/utils/isPrerender'
+import { isPreview } from './tests/utils/isPreview'
+import packageJson from './package.json' with { type: 'json' }
+
+const PORT = await getTestServerPort(
+  `${packageJson.name}${isSpaMode ? '_spa' : ''}${isPreview ? '_preview' : ''}`,
+)
+const START_PORT = await getTestServerPort(
+  `${packageJson.name}${isSpaMode ? '_spa_start' : ''}`,
+)
+const EXTERNAL_PORT = await getDummyServerPort(packageJson.name)
+const baseURL = `http://localhost:${PORT}`
+const spaModeCommand = `pnpm build:spa && pnpm start:spa`
+const ssrModeCommand = `pnpm build && pnpm start`
+const prerenderModeCommand = `pnpm run test:e2e:startDummyServer && pnpm build:prerender && pnpm run test:e2e:stopDummyServer && pnpm start`
+const previewModeCommand = `pnpm build && pnpm preview --port ${PORT}`
+
+const getCommand = () => {
+  if (isSpaMode) return spaModeCommand
+  if (isPrerender) return prerenderModeCommand
+  if (isPreview) return previewModeCommand
+  return ssrModeCommand
+}
+console.log('running in spa mode: ', isSpaMode.toString())
+console.log('running in prerender mode: ', isPrerender.toString())
+console.log('running in preview mode: ', isPreview.toString())
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: './tests',
+  workers: 1,
+  reporter: [['line']],
+
+  globalSetup: './tests/setup/global.setup.ts',
+  globalTeardown: './tests/setup/global.teardown.ts',
+
+  use: {
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    baseURL,
+  },
+
+  webServer: {
+    command: getCommand(),
+    url: baseURL,
+    reuseExistingServer: !process.env.CI,
+    stdout: 'pipe',
+    env: {
+      MODE: process.env.MODE || '',
+      VITE_NODE_ENV: 'test',
+      VITE_EXTERNAL_PORT: String(EXTERNAL_PORT),
+      VITE_SERVER_PORT: String(PORT),
+      START_PORT: String(START_PORT),
+      PORT: String(PORT),
+    },
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+      },
+    },
+  ],
+})

e2e/solid-start/basic-head/server.js

@@ -0,0 +1,67 @@
+import { toNodeHandler } from 'srvx/node'
+import path from 'node:path'
+import express from 'express'
+import { createProxyMiddleware } from 'http-proxy-middleware'
+
+const port = process.env.PORT || 3000
+
+const startPort = process.env.START_PORT || 3001
+
+export async function createStartServer() {
+  const server = (await import('./dist/server/server.js')).default
+  const nodeHandler = toNodeHandler(server.fetch)
+
+  const app = express()
+
+  app.use(express.static('./dist/client'))
+
+  app.use(async (req, res, next) => {
+    try {
+      await nodeHandler(req, res)
+    } catch (error) {
+      next(error)
+    }
+  })
+
+  return { app }
+}
+
+export async function createSpaServer() {
+  const app = express()
+
+  app.use(
+    '/api',
+    createProxyMiddleware({
+      target: `http://localhost:${startPort}/api`, // Replace with your target server's URL
+      changeOrigin: false, // Needed for virtual hosted sites,
+    }),
+  )
+
+  app.use(
+    '/_serverFn',
+    createProxyMiddleware({
+      target: `http://localhost:${startPort}/_serverFn`, // Replace with your target server's URL
+      changeOrigin: false, // Needed for virtual hosted sites,
+    }),
+  )
+
+  app.use(express.static('./dist/client'))
+
+  app.get('/{*splat}', (req, res) => {
+    res.sendFile(path.resolve('./dist/client/index.html'))
+  })
+
+  return { app }
+}
+
+createSpaServer().then(async ({ app }) =>
+  app.listen(port, () => {
+    console.info(`Client Server: http://localhost:${port}`)
+  }),
+)
+
+createStartServer().then(async ({ app }) =>
+  app.listen(startPort, () => {
+    console.info(`Start Server: http://localhost:${startPort}`)
+  }),
+)

e2e/solid-start/basic-head/src/client.tsx

@@ -0,0 +1,10 @@
+// DO NOT DELETE THIS FILE!!!
+// This file is a good smoke test to make sure the custom client entry is working
+import { hydrate } from 'solid-js/web'
+import { StartClient, hydrateStart } from '@tanstack/solid-start/client'
+
+console.log("[client-entry]: using custom client entry in 'src/client.tsx'")
+
+hydrateStart().then((router) => {
+  hydrate(() => <StartClient router={router} />, document)
+})

e2e/solid-start/basic-head/src/components/DefaultCatchBoundary.tsx

@@ -0,0 +1,51 @@
+import {
+  ErrorComponent,
+  Link,
+  rootRouteId,
+  useMatch,
+  useRouter,
+} from '@tanstack/solid-router'
+import type { ErrorComponentProps } from '@tanstack/solid-router'
+
+export function DefaultCatchBoundary({ error }: ErrorComponentProps) {
+  const router = useRouter()
+  const isRoot = useMatch({
+    strict: false,
+    select: (state) => state.id === rootRouteId,
+  })
+
+  console.error(error)
+
+  return (
+    <div class="min-w-0 flex-1 p-4 flex flex-col items-center justify-center gap-6">
+      <ErrorComponent error={error} />
+      <div class="flex gap-2 items-center flex-wrap">
+        <button
+          type="button"
+          onClick={() => {
+            router.invalidate()
+          }}
+          class={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded-sm text-white uppercase font-extrabold`}
+        >
+          Try Again
+        </button>
+        {isRoot() ? (
+          <Link
+            to="/"
+            class={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded-sm text-white uppercase font-extrabold`}
+          >
+            Home
+          </Link>
+        ) : (
+          <button
+            type="button"
+            onClick={() => window.history.back()}
+            class={`px-2 py-1 bg-gray-600 dark:bg-gray-700 rounded-sm text-white uppercase font-extrabold`}
+          >
+            Go Back
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}

e2e/solid-start/basic-head/src/components/NotFound.tsx

@@ -0,0 +1,25 @@
+import { Link } from '@tanstack/solid-router'
+
+export function NotFound({ children }: { children?: any }) {
+  return (
+    <div class="space-y-2 p-2" data-testid="default-not-found-component">
+      <div class="text-gray-600 dark:text-gray-400">
+        {children || <p>The page you are looking for does not exist.</p>}
+      </div>
+      <p class="flex items-center gap-2 flex-wrap">
+        <button
+          onClick={() => window.history.back()}
+          class="bg-emerald-500 text-white px-2 py-1 rounded-sm uppercase font-black text-sm"
+        >
+          Go back
+        </button>
+        <Link
+          to="/"
+          class="bg-cyan-600 text-white px-2 py-1 rounded-sm uppercase font-black text-sm"
+        >
+          Start Over
+        </Link>
+      </p>
+    </div>
+  )
+}

e2e/solid-start/basic-head/src/routeTree.gen.ts

@@ -0,0 +1,86 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as ArticleIdRouteImport } from './routes/article.$id'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ArticleIdRoute = ArticleIdRouteImport.update({
+  id: '/article/$id',
+  path: '/article/$id',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/article/$id': typeof ArticleIdRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/article/$id': typeof ArticleIdRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/article/$id': typeof ArticleIdRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/article/$id'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/article/$id'
+  id: '__root__' | '/' | '/article/$id'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  ArticleIdRoute: typeof ArticleIdRoute
+}
+
+declare module '@tanstack/solid-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/article/$id': {
+      id: '/article/$id'
+      path: '/article/$id'
+      fullPath: '/article/$id'
+      preLoaderRoute: typeof ArticleIdRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  ArticleIdRoute: ArticleIdRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/solid-start'
+declare module '@tanstack/solid-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}

e2e/solid-start/basic-head/src/router.tsx

@@ -0,0 +1,16 @@
+import { createRouter } from '@tanstack/solid-router'
+import { routeTree } from './routeTree.gen'
+import { DefaultCatchBoundary } from './components/DefaultCatchBoundary'
+import { NotFound } from './components/NotFound'
+
+export function getRouter() {
+  const router = createRouter({
+    routeTree,
+    // defaultPreload: 'intent',
+    defaultErrorComponent: DefaultCatchBoundary,
+    defaultNotFoundComponent: () => <NotFound />,
+    scrollRestoration: true,
+  })
+
+  return router
+}