SolidStart: inside the 2.0 monorepo and what the README actually covers

What SolidStart is, and why the main branch is not what most readers expect

SolidStart is the application framework built around Solid, the reactive UI library. It is distributed on npm as @solidjs/start, and the project's own documentation lives at start.solidjs.com and docs.solidjs.com/solid-start. That much is stable. What is not stable is the branch you land on.

The root README states plainly that main is the branch for SolidStart 2.0.0-alpha and is "currently under heavy development", and that current SolidStart is maintained on the 1.x branch. So the repository you clone by default is not the version most production users are running. Release history backs the split: the newest entries are @solidjs/[email protected] on 2026-08-24, 2.0.3 on 2026-08-20 and 2.0.2 on 2026-08-19, all published within a week. A three-patch run inside five days is normal for an alpha line and a poor fit for anyone who wants a frozen surface.

The audience for this repository, as written, is contributors rather than app authors. The README's first bullet sends people building apps to the package README at packages/start/README.md and the official docs, and only then describes how to work on the codebase itself. If you arrived looking for a getting started tutorial, the root README is the wrong document, and that is a deliberate choice rather than an oversight.

The pnpm workspace layout behind @solidjs/start

SolidStart is a pnpm monorepo with nested workspaces, and the README lists the key directories: packages/start holds the core @solidjs/start package, apps/landing-page is the official site, apps/tests contains unit and end-to-end tests built on Vitest and Playwright, and apps/fixtures holds fixture projects used for manual testing.

That split matters when you are debugging. A change to routing or server behaviour lands in packages/start, but the thing that exercises it is a fixture under apps/fixtures, and the thing that would catch a regression is a test under apps/tests. The README is explicit that integration and unit tests live inside their respective packages, while end-to-end tests live in apps/tests projects. Three locations, three different run commands.

Workspace targeting is done with pnpm filters. The README gives the pattern pnpm --filter @solidjs/start ... for reaching a specific package, and the root package.json shows the same idea applied across the tree, for example "packages:build": "pnpm --filter=./packages/* build". The nesting is real: the root package.json also defines lp:dev, lp:build, lp:start and lp:clean, which filter down to landing-page, so the landing page is reachable both through its own scripts and through the workspace filter.

Installing the monorepo and running a fixture

The README's Local Setup section is the only installation path it documents, and it installs the repository rather than an app. Prerequisites are Node.js at the version in .nvmrc, pnpm (globally via npm install -g pnpm, or through Corepack), and Git. Clone and enter the tree first.

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

Then enable the pnpm version pinned in package.json and install. The README notes that pnpm dedupe installs dependencies and cleans the lockfile of duplicates, which it says helps prevent conflicts.

corepack enable
pnpm dedupe

Building everything compiles the packages and the landing page. This is the step that produces the artifacts the tests consume.

pnpm run build:all

For a first real use, the README points at the fixtures: pick a fixture name and run dev with workspace filtering. It gives fixture-basic as the example, so the command below starts that fixture's dev server. What you should see is the fixture app served by the local build of the framework, which is the loop you want when checking a change to packages/start.

pnpm --filter fixture-basic dev

The landing page has its own path from the root directory, pnpm run lp:dev. If the install goes wrong, the README's remedy is pnpm run clean:all followed by a reinstall and rebuild, and it names a missing node_modules as the kind of symptom that calls for it.

Tests, fixtures and the build artifact trap

The test setup has one ordering constraint that is easy to miss. The README says that for unit tests which check build artifacts, the test app must be built first, with pnpm --filter tests run build. Run the unit suite before that build and you are testing against stale or absent output, which is a failure mode of the harness rather than of your change.

Playwright's Chromium binary is a one-time install, and the README scopes it to the tests package.

pnpm --filter tests exec playwright install chromium

After that, unit tests run in watch mode by default, with a CI variant that runs once and a UI mode. End-to-end tests have their own command and a UI variant, and artifacts are cleared with pnpm run clean:test, which the root package.json maps to removing .tmp.

pnpm --filter tests run unit
pnpm --filter tests run unit:ci
pnpm --filter tests run e2e

One detail worth flagging: the README's clean:test target removes .tmp, while the root clean:root target removes ./node_modules, ./.vinxi/ and ./.output/. Those are different directories with different lifetimes, and the .vinxi and .output folders are build output, not test scratch space. If a build looks wrong after a test run, the test cleanup is not what fixes it.

Where the documentation stops

The root README is a contributor guide and it behaves like one. It documents cloning, Corepack, pnpm dedupe, build:all, the test commands, the fixture workflow and the clean targets. It does not document the framework's own API surface: no routing conventions, no server function signatures, no data loading model, no configuration reference for a SolidStart app. It defers all of that to packages/start/README.md and the docs site, and the repository root gives you no fallback if those are thin.

A second gap is versioning guidance. The README says 2.0.0-alpha is under heavy development and that current SolidStart lives on 1.x, but it does not describe how to migrate between them, and it does not state which version a fresh install of @solidjs/start resolves to. The release list shows 2.0.x patch releases shipping through late August 2026, so the alpha line is being published, not just developed. Anyone reading only the README could reasonably install the package and get a major version they did not intend.

The last push to the repository was on 2026-08-24, the same day as the 2.0.4 release. That is recent, so there is no maintenance concern to raise here. The concern is scope: this document is written for people changing the framework, not for people using it.

SolidStart against Next.js and the Vinxi build layer

The nearest comparison is Next.js, and the difference is not feature parity, it is the reactive model underneath. Next.js is built on React and its rendering and caching semantics are tied to React's model. SolidStart is built on Solid, whose fine grained reactivity updates the DOM without a virtual DOM diff, so component code runs once and signals drive updates. If your team's mental model is React hooks and re-render cycles, that difference shows up in everyday component code, not just in benchmarks. The trade is ecosystem size: React's component and tooling ecosystem is far larger, and SolidStart's own docs point you to a smaller set of first party resources.

A second distinction sits inside the repository. The root clean scripts remove .vinxi and .output directories, and the README's lp:clean target removes ./packages/landing-page/.vinxi/ and ./packages/landing-page/.output/. Vinxi is the build and dev server layer the framework runs on, and its presence in the cleanup paths is a reminder that SolidStart's build pipeline is a composition rather than a single tool. That composition is what makes the fixture and test commands necessary: you are not testing one bundler, you are testing how the framework configures the layers beneath it.

Licence, upgrade cost and what the release cadence implies

The repository and the root package.json both carry MIT, and the package is published under the same terms. MIT permits commercial use, modification and redistribution with the licence text retained; that is the extent of what the repository states, and it is not legal advice. For an app framework the practical consequence is that nothing in the licence blocks a closed source product.

Upgrade cost is where the alpha line bites. Three patch releases landed between 2026-08-19 and 2026-08-24, and the README describes 2.0.0-alpha as under heavy development while directing current users to the 1.x branch. A cadence like that means pinning a version and reading the changelog before moving, because patch numbers on an alpha do not carry the same promise they do on a stable line. The repository uses Changesets, visible in the .changeset directory and in the release script ("release": "pnpm build && changeset publish"), so release notes are generated per package rather than as a single project changelog.

The maintenance picture is straightforward: the last push was on 2026-08-24, so the project is not dormant. The upgrade risk is version related, not activity related.

Editorial conclusion

Adopt SolidStart if you are already on Solid and want file based routing plus server functions, and if you are willing to read the 2.0 source because the README stops at contributor setup. Do not adopt it if you need a documented upgrade path from 1.x, or if you need stability guarantees on the main branch: the README itself says 2.0.0-alpha is under heavy development and points current users to the 1.x branch. Before you commit, check the packages/start README and the docs site for the routing and server function APIs you depend on, and confirm which major version your package manager resolves for @solidjs/start.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes