Skip to content

docs: Updated contribution guidelines and README #1948

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
atilafassina merged 6 commits into from
Aug 28, 2025
Merged

docs: Updated contribution guidelines and README #1948

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7dbf5e4
docs: Updated contribution guidelines and README
thomasbuilds Aug 20, 2025
21faeb2
Updated README
thomasbuilds Aug 27, 2025
32fe22e
Revise contributing guidelines for SolidStart
thomasbuilds Aug 27, 2025
272aba0
Fix bun command syntax in README
thomasbuilds Aug 28, 2025
1aad02c
Update CONTRIBUTING.md
thomasbuilds Aug 28, 2025
cf23f4c
Update CONTRIBUTING.md
thomasbuilds Aug 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 141 additions & 17 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,144 @@
# Contributing

Thank you for your interest in contributing to **SolidStart**! We welcome contributions including bug fixes, feature enhancements, documentation improvements, and more.

## Prerequisites

- **Node.js**: Use the version specified in `.nvmrc`, to manage multiple versions across your system, we recommend a version manager such as [fnm](https://github.com/Schniz/fnm), or another of your preference.
- **pnpm**: Install globally via `npm install -g pnpm`. Or let **Corepack** handle it in the setup step below.
- **Git**: Ensure Git is installed for cloning and managing the repository

## Setup

1. Clone the repository
`git clone https://github.com/solidjs/solid-start.git`
2. Install dependencies
`pnpm install`
3. Build dependencies
`pnpm run build:all`
4. Run an example
`pnpm --filter example-hackernews run dev`
5. Make changes and check if things work in examples
6. Add integration tests in `test`, if appropriate
7. Run tests locally
- Setup playwright: `pnpm run install:playwright`
- Run all tests: `pnpm run test:all`
- Show report: `pnpm run show:test-report`

## Requirements

1. Node.js: ^20

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

2. Enable the correct pnpm version specified in package.json

```bash
corepack enable
```

3. Install dependencies

```bash
pnpm install
```

4. Build all packages and the landing page
```bash
pnpm run build:all
```

If you encounter issues (e.g. missing `node_modules`), clean the workspace

```bash
pnpm run clean:all
```

Then reinstall dependencies and rebuild.

## Monorepo Structure

SolidStart is a pnpm-based monorepo with nested workspaces. Key directories include

- **`packages/start`**: The core `@solidjs/start` package.
- **`packages/landing-page`**: The official landing page.
- **`examples/`**: Example projects for testing (a nested workspace; see details below).
- **`packages/tests`**: Unit and end-to-end (E2E) tests using Vitest and Cypress.

Use pnpm filters (e.g. `pnpm --filter @solidjs/start ...`) to target specific packages.
The `examples/` directory is a separate workspace with its own `pnpm-workspace.yaml` and `pnpm-lock.yaml`.

## Developing and Testing Changes

1. Make your changes in the relevant package (e.g. `packages/start`)

2. Rebuild affected packages

```bash
pnpm run packages:build
```

For a full rebuild: `pnpm run build:all`

3. Test your changes

- For examples
```bash
cd examples
pnpm install
pnpm --filter example-hackernews run dev # Runs the HackerNews example
```
- For the landing page (from the root directory)
```bash
pnpm run lp:dev
```

4. Clean builds if needed
```bash
pnpm run packages:clean # Cleans packages' node_modules and dist folders
pnpm run lp:clean # Cleans the landing page
pnpm run clean:root # Cleans root-level caches
```

## Running Tests

Tests are located in `packages/tests`, using Vitest for unit tests and Cypress for E2E tests.

1. Install the Cypress binary (required only once)

```bash
pnpm --filter tests exec cypress install
```

2. For unit tests that check build artifacts, build the test app first

```bash
pnpm --filter tests run build
```

3. Run unit tests

```bash
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

```bash
pnpm --filter tests run e2e:run
```

- Interactive mode: `pnpm --filter tests run e2e:open`
- With dev server: `pnpm --filter tests run e2e`

5. Clean test artifacts
```bash
pnpm run clean:test
```

## Using SolidStart in Your Own Monorepo

When integrating `@solidjs/start` into your own monorepo (e.g. using Yarn workspaces), configure dependency hoisting to ensure proper resolution. This helps runtime components (e.g. `client/index.tsx`) resolve correctly in generated files like `index.html`.

### Yarn v2+

In the project root's `package.json`

```jsonc
{
"installConfig": {
"hoistingLimits": "dependencies"
}
}
```

For pnpm monorepos, define workspaces in `pnpm-workspace.yaml`. If you encounter resolution issues (e.g. missing modules like `h3` from Vinxi), add `shamefully-hoist=true` to your `.npmrc` file. Test for duplicates and adjust configurations as necessary.
122 changes: 19 additions & 103 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
[![Banner](https://assets.solidjs.com/banner?project=Start&type=core)](https://github.com/solidjs)

[![Version](https://img.shields.io/npm/v/@solidjs/start.svg?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@solidjs/start)
[![Downloads](https://img.shields.io/npm/dm/@solidjs/start.svg?style=for-the-badge&color=green)](https://www.npmjs.com/package/@solidjs/start)
[![Stars](https://img.shields.io/github/stars/solidjs/solid-start?style=for-the-badge&color=yellow)](https://github.com/solidjs/solid-start)
[![Discord](https://img.shields.io/discord/722131463138705510?style=for-the-badge&color=5865F2)](https://discord.com/invite/solidjs)
[![Reddit](https://img.shields.io/reddit/subreddit-subscribers/solidjs?style=for-the-badge&color=FF4500)](https://www.reddit.com/r/solidjs/)
<div align="center">

[![Version](https://img.shields.io/npm/v/@solidjs/start.svg?style=for-the-badge&color=blue&logo=npm)](https://npmjs.com/package/@solidjs/start)
[![Downloads](https://img.shields.io/npm/dm/@solidjs/start.svg?style=for-the-badge&color=green&logo=npm)](https://npmjs.com/package/@solidjs/start)
[![Stars](https://img.shields.io/github/stars/solidjs/solid-start?style=for-the-badge&color=yellow&logo=github)](https://github.com/solidjs/solid-start)
[![Discord](https://img.shields.io/discord/722131463138705510?label=join&style=for-the-badge&color=5865F2&logo=discord&logoColor=white)](https://discord.com/invite/solidjs)
[![Reddit](https://img.shields.io/reddit/subreddit-subscribers/solidjs?label=join&style=for-the-badge&color=FF4500&logo=reddit&logoColor=white)](https://reddit.com/r/solidjs)

</div>

**SolidStart** brings fine-grained reactivity fullstack with full flexibility. Built with features like unified rendering and isomorphic code execution, SolidStart enables you to create highly performant and scalable web applications.

Expand All @@ -15,7 +19,7 @@ Explore the official [documentation](https://docs.solidjs.com/solid-start) for d
- **All Rendering Modes**:
- Server-Side Rendering _(SSR)_ with sync, async, and stream [modes](https://docs.solidjs.com/solid-start/reference/server/create-handler)
- Client-Side Rendering _(CSR)_
- Static Site Generation _(SSG)_
- Static Site Generation _(SSG)_ with route [pre-rendering](https://docs.solidjs.com/solid-start/building-your-application/route-prerendering)
- **TypeScript**: Full integration for robust, type-safe development
- **File-Based Routing**: Intuitive routing based on your project’s file structure
- **API Routes**: Dedicated server-side endpoints for seamless API development
Expand All @@ -27,35 +31,21 @@ Explore the official [documentation](https://docs.solidjs.com/solid-start) for d

### Installation

Create a template project with your preferred package manager
Create a SolidStart template project with your preferred package manager

```bash
# using npm
npm create solid@latest -- --solidstart
npm create solid@latest -- -s
```

```bash
# using pnpm
pnpm create solid@latest --solidstart
pnpm create solid@latest -s
```

```bash
# using bun
bun create solid@latest --solidstart
```

1. Follow the CLI prompts to set up your project
2. Navigate to your project directory and install the dependencies

```bash
cd <project-name>
npm install # or pnpm install or bun install
```

3. Start the development server

```bash
npm run dev # or pnpm dev or bun dev
bun create solid@latest --s
```

### Project Structure
Expand All @@ -68,7 +58,7 @@ npm run dev # or pnpm dev or bun dev
- `entry-server.tsx`: Manages server-side request handling
- **Configuration Files**: `app.config.ts`, `package.json`, and more

Learn more about routing in the [documentation](https://docs.solidjs.com/solid-start/building-your-application/routing).
Learn more about [routing](https://docs.solidjs.com/solid-start/building-your-application/routing)

## Adapters

Expand All @@ -79,14 +69,14 @@ import { defineConfig } from "@solidjs/start/config";

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

Presets also include runtimes like Node.js, Bun or Deno. For example, the `node-server` preset enables hosting on your server.
Learn more about [`defineConfig`](https://docs.solidjs.com/solid-start/reference/config/define-config).
Presets also include runtimes like Node.js, Bun or Deno. For example, a preset like `node-server` enables hosting on your server.
Learn more about [`defineConfig`](https://docs.solidjs.com/solid-start/reference/config/define-config)

## Building for Production
## Building

Generate production-ready bundles

Expand All @@ -95,77 +85,3 @@ npm run build # or pnpm build or bun build
```

After the build completes, you’ll be guided through deployment for your specific preset.

## Contributing

Join the SolidJS community and contribute!

- [Discord](https://discord.com/invite/solidjs): Ask for help and discuss ideas
- [Issues](https://github.com/solidjs/solid-start/issues): Report bugs or suggest features
- [Docs Issues](https://github.com/solidjs/solid-docs/issues): Report documentation issues

<details>
<summary><h3>Development Setup</h3></summary>

Use a Node.js version manager compatible with `.node-version`. We recommend [asdf-vm](https://asdf-vm.com/) for macOS and Linux users.

### Monorepo & Package Manager

SolidStart uses `pnpm` as the package manager. Install it globally:

```bash
npm install -g pnpm
```

Install dependencies for the monorepo:

```bash
pnpm install
```

Build the project:

```bash
pnpm build
```

### Monorepo & `package.json` Workspaces

If using a monorepo with `package.json` `"workspaces"` (e.g., [Yarn Workspaces](https://classic.yarnpkg.com/en/docs/workspaces/)), ensure `@solidjs/start` is not hoisted. Add it to the `"nohoist"` field in the workspace root or project root:

**Workspace Root Example**:

```jsonc
{
"workspaces": {
"packages": [
/* ... */
],
"nohoist": ["**/@solidjs/start"]
}
}
```

**Project Root Example**:

```jsonc
{
"workspaces": {
"nohoist": ["@solidjs/start"]
}
}
```

For **Yarn v2+**, use `installConfig` to prevent hoisting:

```jsonc
{
"installConfig": {
"hoistingLimits": "dependencies"
}
}
```

**Note**: Add `@solidjs/start` as a `devDependency` in the child `package.json` to ensure the `/node_modules/@solidjs/start/runtime/entry.jsx` script is available.

</details>
Loading