Skip to content

Commit 358b8eb

Browse files
tdrztudor
andauthored
Update the packages/pglite/README.md detailing the build and contribute processes (#494)
Copied the entire README.md to packages/pglite/README.md --------- Co-authored-by: tudor <tudor@swisstch.com>
1 parent 17e7664 commit 358b8eb

File tree

1 file changed

+53
-8
lines changed

1 file changed

+53
-8
lines changed

packages/pglite/README.md

Lines changed: 53 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333

3434
![PGlite](https://raw.githubusercontent.com/electric-sql/pglite/main/screenshot.png)
3535

36-
PGlite is a WASM Postgres build packaged into a TypeScript client library that enables you to run Postgres in the browser, Node.js and Bun, with no need to install any other dependencies. It is only 3mb gzipped and has support for many Postgres extensions, including [pgvector](https://github.com/pgvector/pgvector).
36+
PGlite is a WASM Postgres build packaged into a TypeScript client library that enables you to run Postgres in the browser, Node.js, Bun and Deno, with no need to install any other dependencies. It is only 3mb gzipped and has support for many Postgres extensions, including [pgvector](https://github.com/pgvector/pgvector).
3737

3838
```javascript
3939
import { PGlite } from "@electric-sql/pglite";
@@ -43,7 +43,7 @@ await db.query("select 'Hello world' as message;");
4343
// -> { rows: [ { message: "Hello world" } ] }
4444
```
4545

46-
It can be used as an ephemeral in-memory database, or with persistence either to the file system (Node/Bun) or indexedDB (Browser).
46+
It can be used as an ephemeral in-memory database, or with persistence either to the file system (Node/Bun/Deno) or indexedDB (Browser).
4747

4848
Unlike previous "Postgres in the browser" projects, PGlite does not use a Linux virtual machine - it is simply Postgres in WASM.
4949

@@ -76,14 +76,28 @@ or to persist the database to indexedDB:
7676
const db = new PGlite("idb://my-pgdata");
7777
```
7878

79-
## Node/Bun
79+
## Node/Bun/Deno
8080

8181
Install into your project:
8282

83+
**NodeJS**
84+
8385
```bash
8486
npm install @electric-sql/pglite
8587
```
8688

89+
**Bun**
90+
91+
```bash
92+
bun install @electric-sql/pglite
93+
```
94+
95+
**Deno**
96+
97+
```bash
98+
deno add npm:@electric-sql/pglite
99+
```
100+
87101
To use the in-memory Postgres:
88102

89103
```javascript
@@ -110,20 +124,51 @@ Fortunately, PostgreSQL includes a "single user mode" primarily intended for com
110124

111125
- PGlite is single user/connection.
112126

113-
## How to contribute
127+
## How to build PGlite and contribute
128+
129+
The build process of PGlite is split into two parts:
130+
131+
1. Building the Postgres WASM module.
132+
2. Building the PGlite client library and other TypeScript packages.
114133

115-
You will need [pnpm](https://pnpm.io/) installed, and a recent version of Node.js (v20 and above).
134+
Docker is required to build the WASM module, along with Node (v20 or above) and [pnpm](https://pnpm.io/) for package management and building the TypeScript packages.
116135

117-
You will also need the Postgres WASM build files, which you download from a comment under the most recently merged PR, labeled as _interim build files_, and place them under `packages/pglite/release`. These are necessary to build PGlite and the dependent workspace projects. We plan to enable a local build in the future to streamline this step.
136+
To start checkout the repository and install dependencies:
118137

119-
Once the requirements are met, you can install dependencies and build the workspace projects:
120138
```bash
139+
git clone https://github.com/electric-sql/pglite
140+
cd pglite
121141
pnpm install
122-
pnpm build
142+
```
143+
144+
To build everything, we have the convenient `pnpm build:all` command in the root of the repository. This command will:
145+
146+
1. Use Docker to build the Postgres WASM module. The artifacts from this are then copied to `/packages/pglite/release`.
147+
2. Build the PGlite client library and other TypeScript packages.
148+
149+
To _only_ build the Postgres WASM module (i.e. point 1 above), run
150+
151+
```bash
152+
pnpm wasm:build
153+
```
154+
155+
If you don't want to build the WASM module and assorted WASM binaries from scratch, you can download them from a comment under the most recently merged PR, labeled as _interim build files_, and place them under `packages/pglite/release`.
156+
157+
To build all TypeScript packages (i.e. point 2 of the above), run:
158+
159+
```bash
160+
pnpm ts:build
123161
```
124162

125163
This will build all packages in the correct order based on their dependency relationships. You can now develop any individual package using the `build` and `test` scripts, as well as the `stylecheck` and `typecheck` scripts to ensure style and type validity.
126164

165+
Or alternatively to build a single package, move into the package directory and run:
166+
167+
```bash
168+
cd packages/pglite
169+
pnpm build
170+
```
171+
127172
When ready to open a PR, run the following command at the root of the repository:
128173
```bash
129174
pnpm changeset

0 commit comments

Comments
 (0)