Skip to content

Commit

Permalink
docs: improve installation docs for Windows
Browse files Browse the repository at this point in the history
  • Loading branch information
typedarray committed Jan 8, 2024
1 parent caf12cf commit e95e233
Showing 1 changed file with 40 additions and 10 deletions.
50 changes: 40 additions & 10 deletions docs/pages/docs/guides/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,53 @@ title: "Installation"
description: "A guide for installing Ponder on any platform."
---

import { Callout } from "nextra/components";
import { Tabs, Callout } from "nextra/components"

# Installation

The [create-ponder CLI tool](/getting-started/new-project) is the best way to get started with Ponder. If it runs without error, your system meets the requirements.

## System requirements

- MacOS, Linux, or Windows (via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)). Windows without WSL is not currently supported.
- MacOS, Linux, or Windows [__using WSL__](#windows).
- [Node.js 18 or 20](https://nodejs.org/en)
- npm, [yarn](https://yarnpkg.com/getting-started/install), or [pnpm](https://pnpm.io/installation) (recommended)

<Callout type="warning">
If you encounter an installation error, try `npm install -g node-gyp` and then
run `create-ponder` again. Ponder often requires `node-gyp` to be installed
globally to build `better-sqlite3` from source
([#1043](https://github.com/WiseLibs/better-sqlite3/issues/1043)).
</Callout>
## FAQ

### Windows

Ponder currently requires WSL (the Windows Subsystem for Linux) to run on Windows machines. To get started, we strongly recommend following this well-written guide for Node.js app development using WSL.

Guide: [Install Node.js on Windows Subsystem for Linux (WSL2)](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl#install-nvm-nodejs-and-npm)

<Callout type="info">We're keen to collaborate with an experienced open-source Windows developer on supporting Windows without WSL. If you'd like to contribute, please chime in on GitHub ([#421](https://github.com/ponder-sh/ponder/issues/421)).</Callout>

### `better-sqlite3` installation error

Ponder's SQLite driver package (`better-sqlite3`) uses a native binary that must be compiled for your device's specific platform and Node version. Most of the time, the installer finds and downloads a prebuilt binary that's compatible with your device.

If no prebuilt binary is found, the installer attempts to build `better-sqlite3` from source ([#1043](https://github.com/WiseLibs/better-sqlite3/issues/1043)) which often fails. If this happens, you might need to install `node-gyp` globally using your package manager:

{/* prettier-ignore */}
<Tabs items={["pnpm", "yarn", "npm"]}>
<Tabs.Tab>
```
pnpm install -g node-gyp
```
</Tabs.Tab>
<Tabs.Tab>
```
yarn add -g node-gyp
```
</Tabs.Tab>
<Tabs.Tab>
```
npm install -g node-gyp
```
</Tabs.Tab>
</Tabs>

Once you've installed `node-gyp`, try running `create-ponder` again.

## Create Ponder

The [Create Ponder CLI tool](/getting-started/new-project) sets up everything automatically for you. If Create Ponder runs without error, your system meets the requirements and you should be good to go.

0 comments on commit e95e233

Please sign in to comment.