solid-agents-project-scaffolder

solid-agents-project-scaffolder

Quick Reference

Project Type Decision Tree

Need a new SolidJS project?
├── Need SSR, file-based routing, server functions, or API routes?
│   └── YES → SolidStart scaffold
│       ├── Full-stack app with data loading? → SolidStart with query/action
│       ├── Static site with prerendering? → SolidStart with SSG preset
│       └── API backend + frontend? → SolidStart with API routes
└── NO → Plain SolidJS scaffold (client-side SPA)
    ├── Simple reactive UI? → Plain SolidJS + Vite
    ├── Need routing? → Plain SolidJS + @solidjs/router
    └── Embedded widget or library? → Plain SolidJS minimal

Critical Warnings

NEVER use create-react-app, next, or any React scaffolding tool for a SolidJS project. The generated configuration, babel presets, and JSX transform are incompatible.

NEVER omit vite-plugin-solid from vite.config.ts. Without it, JSX compilation fails silently or produces React output.

ALWAYS set "jsxImportSource": "solid-js" in tsconfig.json. Without this, TypeScript resolves JSX types from React, causing type errors on SolidJS-specific attributes.

ALWAYS use babel-preset-solid (included via vite-plugin-solid). This preset compiles JSX into SolidJS's fine-grained reactive DOM operations instead of React.createElement calls.

NEVER include react, react-dom, @types/react, or @types/react-dom in dependencies. Their presence causes type conflicts and import confusion.

ALWAYS use solid-js/web for render and hydrate — these are NOT imported from solid-js directly.

---

Plain SolidJS Scaffold (Client-Side SPA)

Required Dependencies

Package	Type	Purpose
solid-js	dependency	Core reactive framework
@solidjs/router	dependency	Client-side routing (if needed)
typescript	devDependency	TypeScript compiler
vite	devDependency	Build tool and dev server
vite-plugin-solid	devDependency	Vite integration for SolidJS JSX compilation
vitest	devDependency	Testing framework
@solidjs/testing-library	devDependency	Component testing utilities
jsdom	devDependency	DOM environment for tests

Project Structure

my-solid-app/
├── public/
│   └── favicon.ico
├── src/
│   ├── components/
│   │   └── Counter.tsx
│   ├── context/
│   │   └── AppContext.tsx
│   ├── lib/
│   │   └── utils.ts
│   ├── App.tsx
│   └── index.tsx
├── test/
│   └── Counter.test.tsx
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── vitest.config.ts
└── .gitignore

Configuration Files

vite.config.ts

import { defineConfig } from "vite";
import solidPlugin from "vite-plugin-solid";

export default defineConfig({
  plugins: [solidPlugin()],
  server: {
    port: 3000,
  },
  build: {
    target: "esnext",
  },
});

tsconfig.json

{
  "compilerOptions": {
    "strict": true,
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "preserve",
    "jsxImportSource": "solid-js",
    "types": ["vite/client"],
    "noEmit": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Entry Point: index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>My Solid App</title>
  </head>
  <body>
    <div id="root"></div>
    <script src="/src/index.tsx" type="module"></script>
  </body>
</html>

Entry Point: src/index.tsx

import { render } from "solid-js/web";
import App from "./App";

const root = document.getElementById("root");
if (!root) throw new Error("Root element not found");

render(() => <App />, root);

---

SolidStart Scaffold (Full-Stack)

Required Dependencies

Package	Type	Purpose
solid-js	dependency	Core reactive framework
@solidjs/router	dependency	Routing (file-based + programmatic)
@solidjs/start	dependency	SolidStart meta-framework
@solidjs/meta	dependency	Document head management
vinxi	devDependency	Build orchestration (Vite + Nitro)
typescript	devDependency	TypeScript compiler
vitest	devDependency	Testing framework
@solidjs/testing-library	devDependency	Component testing utilities
jsdom	devDependency	DOM environment for tests

Project Structure

my-solidstart-app/
├── public/
│   └── favicon.ico
├── src/
│   ├── components/
│   │   └── Counter.tsx
│   ├── context/
│   │   └── AppContext.tsx
│   ├── lib/
│   │   └── utils.ts
│   ├── routes/
│   │   ├── api/
│   │   │   └── hello.ts
│   │   ├── about.tsx
│   │   └── index.tsx
│   ├── app.tsx
│   ├── entry-client.tsx
│   └── entry-server.tsx
├── test/
│   └── Counter.test.tsx
├── app.config.ts
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── .gitignore

Configuration Files

app.config.ts

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

export default defineConfig({});

tsconfig.json (SolidStart)

{
  "compilerOptions": {
    "strict": true,
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "preserve",
    "jsxImportSource": "solid-js",
    "types": ["vinxi/types/client"],
    "noEmit": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "paths": {
      "~/*": ["./src/*"]
    }
  },
  "include": ["src"]
}

src/app.tsx

import { Suspense } from "solid-js";
import { Router } from "@solidjs/router";
import { FileRoutes } from "@solidjs/start/router";
import { MetaProvider } from "@solidjs/meta";

export default function App() {
  return (
    <Router
      root={(props) => (
        <MetaProvider>
          <Suspense>{props.children}</Suspense>
        </MetaProvider>
      )}
    >
      <FileRoutes />
    </Router>
  );
}

src/entry-client.tsx

// @refresh reload
import { mount, StartClient } from "@solidjs/start/client";

mount(() => <StartClient />, document.getElementById("app")!);

src/entry-server.tsx

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" />
          {assets}
        </head>
        <body>
          <div id="app">{children}</div>
          {scripts}
        </body>
      </html>
    )}
  />
));

---

State Management Setup

Context + Store Provider Pattern

ALWAYS use this pattern for shared application state. NEVER use React's useReducer or Redux patterns.

// src/context/AppContext.tsx
import { createContext, useContext, type ParentProps } from "solid-js";
import { createStore } from "solid-js/store";

interface AppState {
  user: { name: string; email: string } | null;
  theme: "light" | "dark";
}

interface AppActions {
  setUser: (user: AppState["user"]) => void;
  toggleTheme: () => void;
}

const AppContext = createContext<[AppState, AppActions]>();

export function AppProvider(props: ParentProps) {
  const [state, setState] = createStore<AppState>({
    user: null,
    theme: "light",
  });

  const actions: AppActions = {
    setUser: (user) => setState("user", user),
    toggleTheme: () =>
      setState("theme", (prev) => (prev === "light" ? "dark" : "light")),
  };

  return (
    <AppContext.Provider value={[state, actions]}>
      {props.children}
    </AppContext.Provider>
  );
}

export function useApp(): [AppState, AppActions] {
  const context = useContext(AppContext);
  if (!context) throw new Error("useApp must be used within AppProvider");
  return context;
}

---

Testing Setup

vitest.config.ts

import { defineConfig } from "vitest/config";
import solidPlugin from "vite-plugin-solid";

export default defineConfig({
  plugins: [solidPlugin()],
  test: {
    environment: "jsdom",
    globals: true,
    transformMode: {
      web: [/\.[jt]sx?$/],
    },
  },
  resolve: {
    conditions: ["development", "browser"],
  },
});

Example Test: test/Counter.test.tsx

import { render, fireEvent, screen } from "@solidjs/testing-library";
import { describe, it, expect } from "vitest";
import Counter from "../src/components/Counter";

describe("Counter", () => {
  it("increments count on click", async () => {
    render(() => <Counter />);
    const button = screen.getByRole("button");
    expect(button).toHaveTextContent("Count: 0");
    fireEvent.click(button);
    expect(button).toHaveTextContent("Count: 1");
  });
});

---

Routing Setup (Plain SolidJS)

When adding routing to a plain SolidJS project, ALWAYS use @solidjs/router with component prop (NEVER use element prop like React Router).

// src/App.tsx (with routing)
import { Router, Route } from "@solidjs/router";
import { lazy } from "solid-js";

const Home = lazy(() => import("./pages/Home"));
const About = lazy(() => import("./pages/About"));
const NotFound = lazy(() => import("./pages/NotFound"));

export default function App() {
  return (
    <Router>
      <Route path="/" component={Home} />
      <Route path="/about" component={About} />
      <Route path="*404" component={NotFound} />
    </Router>
  );
}

---

Reference Links

• references/methods.md -- Scaffolding templates: file listings, config templates, component templates
• references/examples.md -- Complete SolidJS project scaffold, complete SolidStart project scaffold
• references/anti-patterns.md -- Scaffolding mistakes: wrong config, missing babel preset, React boilerplate

Official Sources

• https://docs.solidjs.com/solid-start/getting-started
• https://docs.solidjs.com/guides/getting-started-with-solid
• https://github.com/solidjs/solid
• https://github.com/solidjs/solid-start