Skip to content

Readme setup instructions #6

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
joshua-journey-apps merged 13 commits into from
Jul 16, 2025
Merged

Readme setup instructions #6

Changes from 11 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
9f5bec0
Merge pull request #1 from powersync-community/init
dean-journeyapps Jul 14, 2025
47ef2ac
fixed minimum node version requirement for vite 7
joshua-journey-apps Jul 14, 2025
3ac9b32
remove unnecessary .degitignore
joshua-journey-apps Jul 14, 2025
2ead5a2
Merge pull request #3 from powersync-community/fix-config
michaelbarnes Jul 14, 2025
19a58e2
Merge pull request #2 from powersync-community/fix-infra
michaelbarnes Jul 14, 2025
a613858
update README to include demo GIF and enhance project description
dean-journeyapps Jul 15, 2025
3bf7dea
update README with correct links for PowerSync and Supabase sign-up
dean-journeyapps Jul 15, 2025
988fc6d
fix: update demo GIF link in README
dean-journeyapps Jul 15, 2025
a6f5d4d
chore: update README for improved link formatting and clarity in setu…
dean-journeyapps Jul 16, 2025
d7bdb82
removed demo.gif
dean-journeyapps Jul 16, 2025
f19d5a8
Merge branch 'main' into readme-setup-instructions
dean-journeyapps Jul 16, 2025
91e0914
enhance README: reorganize setup instructions for PowerSync, swopping…
dean-journeyapps Jul 16, 2025
c50a099
refactor(README): convert all HTML links back to standard Markdown hy…
dean-journeyapps Jul 16, 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
171 changes: 123 additions & 48 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,83 +9,116 @@ A templated Vite, TS, React, PowerSync and Supabase project to get you started q
| Tool/Service | Version / Info | Notes |
|------------------|----------------------------|--------------------------------------------------------|
| Node.js (via nvm)| `v20.19.0` | Ensure you run `nvm use` to match the project version |
| PowerSync | Active account required | [Sign up here](https://accounts.journeyapps.com/portal/powersync-signup) |
| Supabase | Active project/account | [Sign up here](https://supabase.com/dashboard/sign-up) |
| PowerSync | Active account required | <a href="https://accounts.journeyapps.com/portal/powersync-signup" target="_blank" rel="noopener noreferrer">Sign up here</a> |
| Supabase | Active project/account | <a href="https://supabase.com/dashboard/sign-up" target="_blank" rel="noopener noreferrer">Sign up here</a> |


## Getting Started
# Getting Started

You have 4 options to get started with this template.
We recommend using the first option for a quick start.
You have 4 options to get started with this template. We recommend using the first option for a quick start.

1. Generate a repository from this [template](https://github.com/powersync-community/vite-react-ts-powersync-supabase/generate)
2. Use [degit](https://github.com/Rich-Harris/degit) to scaffold the project:
<details>
<summary><strong>1. Generate from template (Recommended)</strong></summary>

```bash
npx degit powersync-community/vite-react-ts-powersync-supabase
```
Generate a repository from this <a href="https://github.com/powersync-community/vite-react-ts-powersync-supabase/generate" target="_blank" rel="noopener noreferrer">template</a>.

</details>

<details>
<summary><strong>2. Use degit</strong></summary>

Use <a href="https://github.com/Rich-Harris/degit" target="_blank" rel="noopener noreferrer">degit</a> to scaffold the project:

```bash
npx degit powersync-community/vite-react-ts-powersync-supabase
```

> **Note**: `degit` is a tool that downloads the latest version of a repository without the git history, giving you a clean starting point. Add a second argument to specify your project name (e.g., my-app).

3. Clone the repository directly and install dependencies:
</details>

```bash
git clone https://github.com/powersync-community/vite-react-ts-powersync-supabase.git
```
<details>
<summary><strong>3. Clone the repository</strong></summary>

Clone the repository directly and install dependencies:

4. Start the project using [bolt.new](https://bolt.new):
```bash
git clone https://github.com/powersync-community/vite-react-ts-powersync-supabase.git
```

- Open this [link](https://bolt.new/github.com/powersync-community/vite-react-ts-powersync-supabase/tree/main) to load the project.
- You will see a configuration error in the preview window because the `.env` file has not yet been defined.
- Create a new `.env` file and populate it with the appropriate Supabase and PowerSync credentials, as specified in the `.env.local.template` file included in this repository.
</details>

<details>
<summary><strong>4. Start with bolt.new</strong></summary>

Start the project using <a href="https://bolt.new" target="_blank" rel="noopener noreferrer">bolt.new</a>:

- Open this <a href="https://bolt.new/github.com/powersync-community/vite-react-ts-powersync-supabase/tree/main" target="_blank" rel="noopener noreferrer">link</a> to load the project.
- You will see a configuration error in the preview window because the `.env.local` file has not yet been defined.
- Create a new `.env.local` file and populate it with the appropriate Supabase and PowerSync credentials, as specified in the `.env.local.template` file included in this repository (refer to step 4 "Set up environment").
- Save the file — the app should launch automatically.

</details>

## Usage

After cloning the repository, navigate to the project directory and install the dependencies:

```bash
cd vite-react-ts-powersync-supabase
npm install
npm run dev
```
```bash
cd vite-react-ts-powersync-supabase
npm install
npm run dev
```

# Setup Backend

## 1. Setup Supabase
Follow these steps to set up your backend with Supabase and PowerSync (Or you can follow the <a href="https://docs.powersync.com/integration-guides/supabase-+-powersync" target="_blank" rel="noopener noreferrer">guide</a>).

## Setup Backend
<details>
<summary><strong>Option 1: Setup using the Supabase Dashboard</strong></summary>

### 1. Setup Supabase
Follow these steps to set up your backend with Supabase and PowerSync (Or you can follow the [guide](https://docs.powersync.com/integration-guides/supabase-+-powersync)).
1. <a href="https://supabase.com/dashboard/projects" target="_blank" rel="noopener noreferrer">Create a new project on the Supabase dashboard</a>.
2. Go to the Supabase SQL Editor for your new project and execute the SQL statements in <a href="database.pgsql" target="_blank" rel="noopener noreferrer">database.pgsql</a> to create the database schema, database functions, and publication needed for PowerSync.
3. Enable "anonymous sign-ins" for the project <a href="https://supabase.com/dashboard/project/_/auth/providers" target="_blank" rel="noopener noreferrer">here</a> (demo specific)

#### Setup using the Supabase Dashboard
1. [Create a new project on the Supabase dashboard](https://supabase.com/dashboard/projects).
2. Go to the Supabase SQL Editor for your new project and execute the SQL statements in [`database.pgsql`](database.pgsql) to create the database schema, database functions, and publication needed for PowerSync.
3. Enable "anonymous sign-ins" for the project [here](https://supabase.com/dashboard/project/_/auth/providers) (demo specific)
</details>

<details>
<summary><strong>Option 2: Setup using the Supabase CLI</strong></summary>

#### Setup using the Supabase CLI (optional)
If you prefer using the Supabase CLI, you can set up your project as follows:
1. Login to your Supabase Account `npx supabase login`
2. Initialize your project `npx supabase init`
3. Enable "anonymous sign-ins" for the project [here](https://supabase.com/dashboard/project/_/auth/providers)
4. Copy your project ID from the Supabase dashboard [here](https://supabase.com/dashboard/project/_/settings/general)
3. Enable "anonymous sign-ins" for the project <a href="https://supabase.com/dashboard/project/_/auth/providers" target="_blank" rel="noopener noreferrer">here</a>
4. Copy your project ID from the Supabase dashboard <a href="https://supabase.com/dashboard/project/_/settings/general" target="_blank" rel="noopener noreferrer">here</a>
5. Link your local project `npx supabase link --project-ref <project-id>`
6. Create your first migration with `npx supabase migration new create_powersync_tables` and then copy the contents of [`database.pgsql`](database.pgsql) into the newly created migration file in the `supabase/migrations` directory.
6. Create your first migration with `npx supabase migration new create_powersync_tables` and then copy the contents of <a href="database.pgsql" target="_blank" rel="noopener noreferrer">database.pgsql</a> into the newly created migration file in the `supabase/migrations` directory.
7. Push your tables to the cloud db
```shell
npx supabase db push
```

### 2. Create PowerSync Instance and Connect to Supabase
</details>

# Setup PowerSync

## 2. Create PowerSync Instance and Connect to Supabase

You can set up your PowerSync instance using either the Dashboard or CLI approach:

#### Option 1: Using PowerSync [CLI](https://docs.powersync.com/usage/tools/cli)
<details>
<summary><strong>Option 1: Using PowerSync CLI</strong></summary>

@joshua-journey-apps joshua-journey-apps Jul 16, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think lets swap the option order here to match the one above (dashboard then cli)


> This PowerSync CLI only works with **PowerSync Cloud instances.**
See <a href="https://docs.powersync.com/usage/tools/cli" target="_blank" rel="noopener noreferrer">PowerSync CLI docs</a>.

> This PowerSync CLI only works with **PowerSync Cloud instances.**
> The CLI currently does not support **self-hosted PowerSync instances.**

If you don't have a PowerSync account yet, [sign up here](https://accounts.journeyapps.com/portal/powersync-signup).
If you don't have a PowerSync account yet, <a href="https://accounts.journeyapps.com/portal/powersync-signup" target="_blank" rel="noopener noreferrer">sign up here</a>.

1. **Get your Personal Access Token:**
- Go to the [PowerSync dashboard](https://powersync.journeyapps.com/)
- Go to the <a href="https://powersync.journeyapps.com/" target="_blank" rel="noopener noreferrer">PowerSync dashboard</a>
- Press `Ctrl + Shift + P` (or `Cmd + Shift + P` on Mac)
- Search for "Create Personal Access Token"
- Give it "owner" policy and a descriptive label
Expand Down Expand Up @@ -116,13 +149,16 @@ Follow the prompts to configure:

> After deploying sync rules via CLI, the changes might not be reflected in the dashboard. If you want to see them in the dashboard, simply copy the contents of your `sync-rules.yaml` file and paste them into the dashboard's sync-rules editor, then redeploy.

#### Option 2: Using PowerSync Dashboard
</details>

<details>
<summary><strong>Option 2: Using PowerSync Dashboard</strong></summary>

If you prefer using the web interface:

1. In the [PowerSync dashboard](https://powersync.journeyapps.com/), create a new PowerSync instance:
1. In the <a href="https://powersync.journeyapps.com/" target="_blank" rel="noopener noreferrer">PowerSync dashboard</a>, create a new PowerSync instance:
- Right-click on 'PowerSync Project' in the project tree on the left and click "Create new instance"
- Pick a name for the instance e.g. "Yjs Demo Test" and proceed.
- Pick a name for the instance e.g. "PowerSyncDemoInstance" and proceed.

2. In the "Edit Instance" dialog that follows, click on the "Connections" tab:
- Click on the "+" button to create a new database connection.
Expand All @@ -133,12 +169,51 @@ If you prefer using the web interface:
- Tick the "Use Supabase Auth" checkbox and configure the JWT secret.
- Click "Save" to save all the changes to your PowerSync instance. The instance will now be deployed — this may take a minute or two.

### 3. Deploy Sync Rules
</details>

## 3. Deploy Sync Rules

<details>
<summary><strong>Option 1: Using CLI (if you used CLI setup above)</strong></summary>

#### Option 1: Using CLI (if you used CLI setup above)
The sync rules are already deployed if you followed the CLI setup steps above.

#### Option 2: Using Dashboard
1. Open the [`sync-rules.yaml`](sync-rules.yaml) in this repo and copy the contents.
2. In the [PowerSync dashboard](https://powersync.journeyapps.com/), paste that into the 'sync-rules.yaml' editor panel.
3. Click the "Deploy sync rules" button and select your PowerSync instance from the drop-down list.
</details>

<details>
<summary><strong>Option 2: Using Dashboard</strong></summary>

1. Open the <a href="sync-rules.yaml" target="_blank" rel="noopener noreferrer">sync-rules.yaml</a> in this repo and copy the contents.
2. In the <a href="https://powersync.journeyapps.com/" target="_blank" rel="noopener noreferrer">PowerSync dashboard</a>, paste that into the 'sync-rules.yaml' editor panel.
3. Click the "Deploy sync rules" button and select your PowerSync instance from the drop-down list.

</details>

## 4. Set up environment

First, copy the environment template file:
```bash
cp .env.local.template .env.local
```

Then set the following environment variables in your `.env.local` file:

```bash
VITE_SUPABASE_URL=
VITE_SUPABASE_ANON_KEY=
VITE_POWERSYNC_URL=
```

### How to get these values:

**VITE_SUPABASE_URL & VITE_SUPABASE_ANON_KEY:**
1. Go to your <a href="https://app.supabase.com" target="_blank" rel="noopener noreferrer">Supabase Dashboard</a>
2. Select your project
3. For the URL: Navigate to Project Settings → Data API and copy the "Project URL" for `VITE_SUPABASE_URL`
4. For the key: Navigate to Project Settings → API Keys and copy the "anon public" key for `VITE_SUPABASE_ANON_KEY`
Comment on lines +209 to +219

@joshua-journey-apps joshua-journey-apps Jul 16, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could provide a single link for ease of use


**VITE_POWERSYNC_URL:**
1. Go to your <a href="https://powersync.journeyapps.com/" target="_blank" rel="noopener noreferrer">PowerSync Dashboard</a>
2. Select your project
3. Navigate to your PowerSync instance
4. Copy the "Instance URL" for `VITE_POWERSYNC_URL`