SolidStart 最小应用指南：从 bare 脚手架掌握项目创建、开发调试与 preset 构建部署

• Web框架
• 前端

SolidStart 是 Solid 生态的全栈应用框架，而apps/fixtures/bare是仓库中最精简的"裸"脚手架：没有路由、没有 Meta 标签、没有多余依赖，仅保留启动一个 SolidStart 应用所必需的最小文件集。本篇以该脚手架的 README 为主线，结合仓库内真实源码，完整讲解"创建项目 → 安装依赖 → 启动开发 → 构建部署"的闭环，并深入解释solidStart()Vite 插件与 Nitro preset 机制背后的实现原理，帮助读者从零搭建并真正理解一个 SolidStart 项目的每个组成部分。

bare 脚手架：SolidStart 的最小可运行骨架

仓库中的 apps/fixtures/bare 是一个private的测试用 fixture，它的定位正如其名——"bare"（裸的）：只包含运行一个 SolidStart 应用所必需的最少内容。它是验证框架能否在"零配置、零额外特性"条件下正常工作的基线项目，也是理解 SolidStart 工程结构的最佳入门样例。

其 README.md 开篇即点明项目宗旨：

Everything you need to build a Solid project, powered bysolid-start.

即"构建 Solid 项目所需的一切，都由 solid-start 提供"。这份 README 虽然简短，却覆盖了 SolidStart 从创建到部署的完整命令链，是官方脚手架模板（npm init solid生成的默认项目）README 的标准内容。下面逐节展开。

创建项目：npm init solid@latest

README 给出了两种创建方式：

# 在当前目录创建新项目 npm init solid@latest # 在 my-app 目录下创建新项目 npm init solid@latest my-app

npm init solid@latest会拉取官方脚手架模板，并支持交互式选择 TypeScript/JavaScript 等选项。仓库中的bare与 bare-js 两个 fixture 恰好对应模板的两类产物形态：

• apps/fixtures/bare：TypeScript 版本，含tsconfig.json与.tsx源码；
• apps/fixtures/bare-js：JavaScript 版本，全部为.jsx源码，无tsconfig.json。

两者除语言差异外结构完全一致，均通过 vite.config.ts（或vite.config.js）接入框架。

创建完成后，需要安装依赖。README 明确说明可使用npm install、pnpm install或yarn任一包管理器；当前仓库使用 pnpm workspace 管理，其 pnpm-workspace.yaml 中的@solidjs/start以workspace:*形式依赖本地包源码，普通用户从模板创建的项目则安装 npm 发布版。

依赖基线：从 package.json 看懂最小依赖集

查看 apps/fixtures/bare/package.json，最小项目的依赖只有四项：

{ "name": "fixture-bare", "private": true, "type": "module", "scripts": { "dev": "vite dev", "build": "vite build" }, "dependencies": { "@solidjs/start": "workspace:*", "nitro": "^3.0.260610-beta", "solid-js": "^1.9.15", "vite": "^8.1.5" }, "engines": { "node": ">=24" } }

几个值得注意的细节：

• "type": "module"：项目以 ESM 模式运行；
• "dev": "vite dev"、"build": "vite build"：脚本直接透传 Vite 命令，SolidStart 的构建逻辑全部封装在 Vite 插件内部；
• nitro是显式依赖：SolidStart 的服务端构建基于 Nitro，需要在项目中显式声明；
• "engines": { "node": ">=24" }：当前版本要求 Node.js 24 及以上，这是运行本仓库 fixture 的前提条件；
• "private": true：fixture 仅供仓库内部测试，不发布。

深入项目骨架：从源码看懂 SolidStart 的最小组成

bare 脚手架去掉public/静态资源后，源码只有四个文件，每一个都对应 SolidStart 的一个核心概念。逐一拆解如下。

1. vite.config.ts：框架的接入点

vite.config.ts 全文仅 7 行，却完整接入了框架：

import { nitro } from "nitro/vite"; import { defineConfig } from "vite"; import { solidStart } from "../../../packages/start/src/config"; export default defineConfig({ plugins: [solidStart(), nitro()], });

其中solidStart()来自仓库内的 packages/start/src/config/index.ts，是框架的核心 Vite 插件；nitro()则接入 Nitro 作为服务端运行时。两者组合，让vite dev同时具备客户端构建、服务端渲染与 API 路由能力。

2. src/app.tsx：应用根组件

app.tsx 是一个使用 Solid 响应式原语的经典计数器：

import { createSignal } from "solid-js"; import "./app.css"; export default function App() { const [count, setCount] = createSignal(0); return ( <main> <h1>Hello world!</h1> <button class="increment" onClick={() => setCount(count() + 1)} type="button"> Clicks: {count()} </button> <p> Visit start.solidjs.com to learn how to build SolidStart apps. </p> </main> ); }

注意两点：App是默认导出（框架按约定从appRoot目录寻找app.{j,t}sx作为应用入口）；CSS 通过import "./app.css"直接引入，样式在构建时会被自动收集。

3. src/entry-client.tsx：客户端挂载入口

entry-client.tsx 负责浏览器端的水合（hydration）：

// @refresh reload import { mount, StartClient } from "@solidjs/start/client"; mount(() => <StartClient />, document.getElementById("app")!);

mount将StartClient挂载到服务端渲染输出的<div id="app">节点上，完成客户端激活。文件首行的// @refresh reload注释是 Solid 的 Fast Refresh 标记，配合solidStart()插件在开发环境提供热更新。

4. src/entry-server.tsx：服务端渲染入口

entry-server.tsx 使用createHandler定义服务端请求处理器：

// @refresh reload 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> )} /> ));

createHandler返回的处理器即 SSR 的 HTML 模板函数：children是服务端渲染出的组件树，assets是收集到的样式与资源标签，scripts是客户端水合脚本。从这里可以看到服务端渲染的完整数据流——组件在服务端渲染为 HTML，再由客户端脚本接管。

5. tsconfig.json：TS 项目的基础配置

tsconfig.json 中除了常规的严格模式配置，有两项与 SolidStart 强相关：

{ "compilerOptions": { "jsx": "preserve", "jsxImportSource": "solid-js", "types": ["@solidjs/start/env"], "paths": { "~/*": ["./src/*"] } } }

• jsxImportSource: "solid-js"：让 JSX 按 Solid 语义编译；
• types: ["@solidjs/start/env"]：引入框架的 env.d.ts 类型声明；
• paths: { "~/*": ["./src/*"] }：约定~/别名指向src/目录，这是 SolidStart 应用代码导入的惯用写法。

开发调试：npm run dev

安装依赖后，README 给出开发命令：

npm run dev # 或启动服务器并自动打开浏览器新标签页 npm run dev -- --open

npm run dev实际执行vite dev（见 package.json），-- --open将--open参数透传给 Vite，让它在启动后自动唤起浏览器。

开发服务器的能力来自solidStart()插件返回的插件数组（见 packages/start/src/config/index.ts 的solidStart()函数），其中关键的几个子插件：

• devServer：接管开发期服务端渲染请求；
• fsRoutes：基于src/routes目录自动生成客户端与 SSR 路由（见 fs-router.ts）；
• manifest：生成路由与资源清单；
• envPlugin：提供$env环境变量处理；
• serverFunctionsPlugin：编译"use server"服务端函数指令（见 directives）。

这些插件让vite dev一个命令就同时提供 Vite 的模块热更新（HMR）与 SolidStart 的 SSR 开发能力。

构建与部署：preset 机制

README 关于构建的核心论述值得完整引用：

Solid apps are built withpresets, which optimise your project for deployment to different environments.

By default,npm run buildwill generate a Node app that you can run withnpm start. To use a different preset, add it to thedevDependenciesinpackage.jsonand specify in yourapp.config.js.

翻译与展开如下：

默认构建：Node 应用

不额外配置时，npm run build（实际执行vite build）会生成一个可直接运行的 Node 应用：

npm run build # 生成 dist/ 产物 npm start # 启动生产服务器

构建产物按环境分为dist/client与dist/server两部分——从源码看，solidStart()插件在 config/index.ts 中通过 Vite 8 的多环境（environments）机制分别配置了client（appType: "custom"，输出dist/client）与server（SSR 模式，输出dist/server），并在builder.buildApp中保证先构建客户端再构建服务端。

自定义 preset：针对不同部署环境优化

SolidStart 将"目标部署环境"抽象为preset概念。不同的 preset 会对产物做针对性优化——例如生成适合 Vercel、Netlify、Cloudflare Workers、Deno 等平台格式的部署包。README 给出的自定义步骤是：

1. 将目标 preset 加入package.json的devDependencies；
2. 在app.config.js中指定该 preset。

需要说明的是：当前仓库源码显示配置方式已经演进。在 packages/start/src/config/index.ts 中，SolidStartOptions接口的文档注释明确写道：

Configuration options for SolidStart. (previously inapp.config.ts)

并引用了官方迁移指南（"move framework configuration into vite.config.ts"）。也就是说，在较新版本中框架配置已从独立的app.config.ts/app.config.js迁移进vite.config.ts，通过solidStart(options)传入——bare fixture 的 vite.config.ts 正是这一新写法的实证。因此实际使用中，preset 的指定可写作：

// vite.config.ts import { nitro } from "nitro/vite"; import { defineConfig } from "vite"; import { solidStart } from "@solidjs/start/config"; export default defineConfig({ plugins: [ solidStart({ /* framework 配置 */ }), nitro({ preset: "你的目标 preset 名" }), ], });

（若使用的是旧版本脚手架，仍可按 README 所述在app.config.js中配置。）具体可选 preset 名称以你所安装的 Nitro 版本文档为准，本文不展开未经验证的清单。

源码级验证：solidStart() 插件支持哪些配置

围绕"配置"这一点，从 packages/start/src/config/index.ts 的SolidStartOptions接口可以看到框架当前支持的核心配置项及其默认值：

solidStart()实现中还会执行几项关键约定（均有源码佐证）：

• 通过globSync在appRoot下寻找app.{j,t}sx作为应用入口，找不到则直接抛错（config/index.ts 中Could not find an app jsx/tsx entry）；
• 约定入口文件必须命名为entry-client与entry-server（拼接到appRoot后）；
• 内置noExternal: ["@solidjs/start", "h3", "cookie-es"]，强制这些模块走 Vite 打包流程，避免包管理器提升（hoisting）导致的版本错位问题；
• 通过define注入import.meta.env.START_SSR、START_APP_ENTRY、SEROVAL_MODE等编译期常量。

这些配置与约定，构成了vite dev/vite build背后完整的行为基线。对 bare 这类零配置项目而言，所有默认值恰好让框架"开箱即用"——这正是最小脚手架的意义所在。

小结

从 apps/fixtures/bare 这个最小 fixture 出发，可以完整走通 SolidStart 的核心工作流：

1. 创建：npm init solid@latest（可带目标目录名）生成脚手架；
2. 安装：npm install/pnpm install/yarn；
3. 开发：npm run dev（-- --open可自动开浏览器），底层由solidStart()+nitro()两个 Vite 插件驱动，提供 SSR、HMR 与文件路由；
4. 构建：npm run build默认产出可运行的 Node 应用，npm start启动；针对不同部署平台可选用 preset 优化产物（新版本在vite.config.ts中配置，旧版本按 README 走app.config.js）。

理解了 bare 脚手架的四个源码文件——app.tsx（应用根组件）、entry-client.tsx（水合入口）、entry-server.tsx（SSR 模板）、vite.config.ts（框架接入点）——就掌握了所有 SolidStart 应用共享的骨架。在此之上添加routes目录、middleware与"use server"函数，即可逐步构建出完整的全栈应用。

• Web框架
• 前端