| name | solidstart-entrypoints |
| description | SolidStart entrypoints: app.tsx for isomorphic root, entry-client.tsx for browser initialization, entry-server.tsx for SSR setup, app.config.ts for build configuration. |
| metadata | {"globs":["src/app.tsx","src/entry-*.tsx","app.config.ts","**/app.config.*"]} |
SolidStart Entrypoints
Complete guide to customizing SolidStart entrypoints. Entrypoints control how your app initializes on both client and server.
app.tsx - Isomorphic Root
The App component is the isomorphic (shared on server and browser) entry point. This is where code runs on both sides.
Basic Example (with Routing)
import { A, Router } from "@solidjs/router";
import { FileRoutes } from "@solidjs/start/router";
import { Suspense } from "solid-js";
export default function App() {
return (
<Router
root={(props) => (
<>
<nav>
<A href="/">Index</A>
<A href="/about">About</A>
</nav>
<Suspense>{props.children}</Suspense>
</>
)}
>
<FileRoutes />
</Router>
);
}
Critical: Always wrap router root with <Suspense> - routes are lazy-loaded.
Bare Example (no routing)
export default function App() {
return (
<main>
<h1>Hello world!</h1>
</main>
);
}
Key points:
- Runs on both server and client
- Define router setup here
- Add global layouts, providers, context
- Shared initialization logic
entry-client.tsx - Browser Entry
entry-client.tsx is where the application starts in the browser. It mounts the app to the DOM.
Basic Setup
import { mount, StartClient } from "@solidjs/start/client";
mount(() => <StartClient />, document.getElementById("app")!);
Custom Client Initialization
import { mount, StartClient } from "@solidjs/start/client";
if ("serviceWorker" in navigator) {
navigator.serviceWorker.register("/sw.js");
}
console.log("Client starting");
mount(() => <StartClient />, document.getElementById("app")!);
Use cases:
- Service worker registration
- Client-only initialization
- Browser API setup
- Analytics initialization
- Client-side routing setup
Important: This file runs only in the browser, not on the server.
entry-server.tsx - Server Entry
entry-server.tsx is where the application starts on the server. It defines the HTML document structure.
Basic Setup
import { createHandler, StartServer } from "@solidjs/start/server";
export default createHandler(() => (
<StartServer
document={({ assets, children, scripts }) => (
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="icon" href="/favicon.ico" />
{assets}
</head>
<body>
<div id="app">{children}</div>
{scripts}
</body>
</html>
)}
/>
));
Custom Document Structure
import { createHandler, StartServer } from "@solidjs/start/server";
export default createHandler(() => (
<StartServer
document={({ assets, children, scripts }) => (
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="description" content="My SolidStart app" />
<link rel="icon" href="/favicon.ico" />
<link rel="stylesheet" href="/styles.css" />
{assets}
</head>
<body>
<noscript>You need to enable JavaScript to run this app.</noscript>
<div id="app">{children}</div>
{scripts}
</body>
</html>
)}
/>
));
SSR Modes
Configure SSR mode in createHandler:
import { createHandler, StartServer } from "@solidjs/start/server";
export default createHandler(() => <StartServer document={...} />);
export default createHandler(
() => <StartServer document={...} />,
{ mode: "async" }
);
export default createHandler(
() => <StartServer document={...} />,
{ mode: "stream" }
);
Document props:
assets: CSS and other asset linkschildren: Rendered app contentscripts: JavaScript bundles
app.config.ts - Build Configuration
The app.config.ts is the root configuration file for SolidStart, Vinxi, Vite, and Nitro.
Basic Configuration
import { defineConfig } from "@solidjs/start/config";
export default defineConfig({});
Advanced Configuration
import { defineConfig } from "@solidjs/start/config";
export default defineConfig({
server: {
preset: "node-server",
},
vite: {
build: {
target: "esnext",
},
},
nitro: {
preset: "node-server",
},
});
Configuration options:
server: Server preset and settingsvite: Vite build configurationnitro: Nitro server configurationrouter: Router configurationssr: SSR mode settings
Common Patterns
Adding Global Providers
import { Router } from "@solidjs/router";
import { FileRoutes } from "@solidjs/start/router";
import { Suspense } from "solid-js";
import { ThemeProvider } from "./contexts/ThemeContext";
export default function App() {
return (
<ThemeProvider>
<Router root={(props) => <Suspense>{props.children}</Suspense>}>
<FileRoutes />
</Router>
</ThemeProvider>
);
}
Custom Error Boundaries
import { ErrorBoundary } from "solid-js";
import { Router } from "@solidjs/router";
import { FileRoutes } from "@solidjs/start/router";
export default function App() {
return (
<ErrorBoundary fallback={(err) => <div>Error: {err.toString()}</div>}>
<Router root={(props) => <Suspense>{props.children}</Suspense>}>
<FileRoutes />
</Router>
</ErrorBoundary>
);
}
Service Worker Registration
import { mount, StartClient } from "@solidjs/start/client";
if ("serviceWorker" in navigator) {
window.addEventListener("load", () => {
navigator.serviceWorker
.register("/sw.js")
.then((registration) => {
console.log("SW registered:", registration);
})
.catch((error) => {
console.log("SW registration failed:", error);
});
});
}
mount(() => <StartClient />, document.getElementById("app")!);
Custom HTML Document
import { createHandler, StartServer } from "@solidjs/start/server";
export default createHandler(() => (
<StartServer
document={({ assets, children, scripts }) => (
<html lang="en" data-theme="dark">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>My App</title>
<link rel="icon" href="/favicon.ico" />
<link rel="preconnect" href="https://fonts.googleapis.com" />
{assets}
</head>
<body>
<div id="app">{children}</div>
{scripts}
</body>
</html>
)}
/>
));
Environment-Specific Configuration
import { defineConfig } from "@solidjs/start/config";
export default defineConfig({
server: {
preset: process.env.NODE_ENV === "production"
? "node-server"
: "node-dev",
},
vite: {
server: {
port: process.env.PORT ? parseInt(process.env.PORT) : 3000,
},
},
});
File Structure
src/
├── app.tsx # Isomorphic root component
├── entry-client.tsx # Browser entry point
├── entry-server.tsx # Server entry point
app.config.ts # Build configuration
Best Practices
-
Keep app.tsx isomorphic:
- Don't use browser-only APIs
- Use
isServer checks if needed
- Shared logic only
-
Client-only code in entry-client.tsx:
- Service workers
- Browser APIs
- Client-side analytics
-
Server-only code in entry-server.tsx:
- HTML document structure
- Meta tags
- Server-side initialization
-
Configuration in app.config.ts:
- Build settings
- Server presets
- Vite/Nitro config
-
Always wrap router with Suspense:
- Routes are lazy-loaded
- Suspense handles loading states
Summary
- app.tsx: Isomorphic root, router setup, global providers
- entry-client.tsx: Browser initialization, service workers
- entry-server.tsx: HTML document structure, SSR setup
- app.config.ts: Build and server configuration
