SolidStart Documentation

SolidStart uses a specific directory structure for assets, routing, and application entry points:

• public/: Static assets (icons, images, fonts).
• src/: Core application code (aliased to ~/).
  • routes/: File-based routing for pages and API endpoints.
  • app.tsx: The root component of your application.
  • entry-client.tsx: Handles client-side hydration.
  • entry-server.tsx: Manages server-side request handling.
• app.config.ts: Main configuration file for the application and adapters.

Tests are located in apps/tests. Follow these steps to run them:

1. Install Playwright Chromium binary (required once):

   pnpm --filter tests exec playwright install chromium

2. **Build the test app** (required for unit tests checking build artifacts):
   ```bash
pnpm --filter tests run build

3. Run Unit Tests:
   • Watch mode: pnpm --filter tests run unit
   • CI mode (run once): pnpm --filter tests run unit:ci
   • UI mode: pnpm --filter tests run unit:ui
4. Run E2E Tests:
   • Standard: pnpm --filter tests run e2e
   • UI mode: pnpm --filter tests run e2e:ui

To clean test artifacts, use:

pnpm run clean:test

To set up the SolidStart monorepo for development, follow these steps:

1. Clone the repository:

   git clone https://github.com/solidjs/solid-start.git
   cd solid-start

2. Enable the pnpm version specified in package.json using Corepack:

   corepack enable

3. Install dependencies and clean the lockfile duplicates:

   pnpm dedupe

4. Build all packages and the landing page:

   pnpm run build:all

If you encounter issues like missing node_modules, clean the workspace using:

pnpm run clean:all

Then reinstall and rebuild.

Create a new SolidStart project using your preferred package manager with the -s (or --s) flag to use the starter template.

# using npm
npm create solid@latest -- -s

# using pnpm
pnpm create solid@latest -s

# using bun
bun create solid@latest --s

Generate production-ready bundles using the build script defined in your package.json.

npm run build # or pnpm build or bun build

When making changes to specific packages (e.g., packages/start):

1. Rebuild affected packages:
   • For specific packages: pnpm run packages:build
   • For a full rebuild: pnpm run build:all
2. Test changes using fixtures: Use workspace filtering to run dev for a specific fixture:

   pnpm --filter <fixture-name> dev

   (Example: pnpm --filter fixture-basic dev)
3. Test the landing page:

   pnpm run lp:dev

4. **Clean builds**:
   - Clean packages: `pnpm run packages:clean`
   - Clean landing page: `pnpm run lp:clean`
   - Clean root caches: `pnpm run clean:root`

To deploy to specific platforms like Vercel, Netlify, or Cloudflare, or to use specific runtimes like Node.js, Bun, or Deno, configure the server.preset option within defineConfig in your app.config.ts file.

import { defineConfig } from "@solidjs/start/config";

export default defineConfig({
  ssr: true, // false for client-side rendering only
  server: { preset: "netlify" },
});

You can provide a custom module to intercept and process errors thrown within server functions before they are serialized and sent to the client.

Provide the path to a module via serverFunctions.onError. The module's default export should be a function called with the error. You can return a new value to send instead of the error, or return undefined to proceed with the original error.

The ui.config.json file defines the configuration for the UI component system. It specifies whether TSX is enabled, the directory where components are located, Tailwind CSS integration paths, and path aliases.

{
  "tsx": true,
  "componentDir": "./src/components/ui",
  "tailwind": {
    "config": "",
    "css": "src/root.css"
  },
  "aliases": {
    "path": "~/*"
  }
}

You can control how data is serialized when crossing the server-client boundary (e.g., in server functions or actions) using the serialization option.

• mode: "json": (Default) Uses standard JSON. It is CSP-friendly and works with JSON.parse, but results in larger payloads.
• mode: "js": Uses a custom binary format (Seroval). It is more efficient but requires eval() on the client, which may be blocked by strict Content Security Policies (CSP).
• plugins: A path to a module that exports an array of custom Seroval plugins. Use this to handle custom classes like ORM IDs, Decimals, or Temporal objects.