Readme setup instructions

README.md

@@ -9,83 +9,136 @@ 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:
+
+```bash
+git clone https://github.com/powersync-community/vite-react-ts-powersync-supabase.git
+```
+
+</details>
 
-4. Start the project using [bolt.new](https://bolt.new):
+<details>
+<summary><strong>4. Start with bolt.new</strong></summary>
 
-- 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.
+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>).
+
+<details>
+<summary><strong>Option 1: Setup using the Supabase Dashboard</strong></summary>
 
-## Setup Backend
+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)
 
-### 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)).
+</details>
 
-#### 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>
+<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: Setup using the PowerSync Dashboard</strong></summary>
+
+If you prefer using the web interface:
+
+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. "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.
+   - Input the credentials from the project you created in Supabase. In the Supabase dashboard, under your project you can go to "Project Settings" and then "Database" and choose "URI" under "Connection string", **untick the "Use connection pooling" option** to use the direct connection, and then copy & paste the connection string into the PowerSync dashboard "URI" field, and then enter your database password at the "Password" field.
+   - Click the "Test connection" button and you should see "Connection success!"
+
+3. Click on the "Credentials" tab of the "Edit Instance" dialog:
+   - 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.
+
+</details>
+
+<details>
+<summary><strong>Option 2: Setup using the PowerSync CLI</strong></summary>
 
-> 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
@@ -116,29 +169,57 @@ 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>
 
-If you prefer using the web interface:
+## 3. Deploy Sync Rules
 
-1. In the [PowerSync dashboard](https://powersync.journeyapps.com/), 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.
+<details>
+<summary><strong>Option 1: Using CLI (if you used CLI setup above)</strong></summary>
 
-2. In the "Edit Instance" dialog that follows, click on the "Connections" tab:
-   - Click on the "+" button to create a new database connection.
-   - Input the credentials from the project you created in Supabase. In the Supabase dashboard, under your project you can go to "Project Settings" and then "Database" and choose "URI" under "Connection string", **untick the "Use connection pooling" option** to use the direct connection, and then copy & paste the connection string into the PowerSync dashboard "URI" field, and then enter your database password at the "Password" field.
-   - Click the "Test connection" button and you should see "Connection success!"
+The sync rules are already deployed if you followed the CLI setup steps above.
 
-3. Click on the "Credentials" tab of the "Edit Instance" dialog:
-   - 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.
+</details>
 
-### 3. Deploy Sync Rules
+<details>
+<summary><strong>Option 2: Using Dashboard</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.
+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:**
+
+**Quick Access:** For convenience, you can access both settings directly:
+- [API Settings & URL](https://supabase.com/dashboard/project/_/settings/api)
+- [API Keys](https://supabase.com/dashboard/project/_/settings/api-keys)
+
+**Detailed Instructions:**
+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`
 
-#### 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.
+**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`