Merge pull request #1 from powersync-community/init

Initial implementation of the template

Author: dean-journeyapps

.degitignore

@@ -0,0 +1,15 @@
+# GitHub Actions and workflows
+.github/
+
+# Development files
+.vscode/
+.idea/
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

.env.local.template

@@ -0,0 +1,5 @@
+# Copy this template: `cp .env.local.template .env.local`
+# Edit .env.local and enter your Supabase and PowerSync project details.
+VITE_SUPABASE_URL=https://foo.supabase.co
+VITE_SUPABASE_ANON_KEY=foo
+VITE_POWERSYNC_URL=https://foo.powersync.journeyapps.com

.github/dependabot.yml

@@ -0,0 +1,41 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "sunday"
+    open-pull-requests-limit: 10
+    reviewers:
+      - "dean-journeyapps"
+      - "joshua-journey-apps"
+      - "michaelbarnes"
+    ignore:
+      # Ignore major version updates for critical deps
+      - dependency-name: "react"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "react-dom"
+        update-types: ["version-update:semver-major"]
+    # Allow security updates for all dependencies
+    allow:
+      - dependency-type: "all"
+    groups:
+      react-ecosystem:
+        patterns:
+          - "react*"
+          - "@types/react*"
+      build-tools:
+        patterns:
+          - "webpack*"
+          - "babel*"
+          - "eslint*"
+          - "vite*"
+      powersync:
+        patterns:
+          - "@powersync/*"
+          - "powersync*"
+      testing:
+        patterns:
+          - "jest*"
+          - "@testing-library/*"
+          - "vitest*"

.github/pull_request_template.md

@@ -0,0 +1,5 @@
+## Description
+
+## Work Done
+
+## How to Test

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+      - name: Run linting
+        run: npm run lint
+      - name: Run type checking
+        run: npm run type-check
+      - name: Run build
+        run: npm run build

.gitignore

@@ -0,0 +1,9 @@
+.env
+.env.local
+.idea
+node_modules
+dist
+.DS_Store
+.env.local
+.env
+.vscode

.nvmrc

@@ -0,0 +1 @@
+v20.12.1

LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

README.md

@@ -1 +1,133 @@
-# vite-react-ts-powersync-supabase
+# Vite + React + TS + PowerSync + Supabase
+
+A template Vite, TS, React, PowerSync and Supabase project to get you started quickly with building offline-first applications with PowerSync and Supabase.
+
+## Getting Started
+
+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:
+
+   ```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:
+
+   ```bash
+   git clone https://github.com/powersync-community/vite-react-ts-powersync-supabase.git
+   ```
+
+4. Start the project using [bolt.new](https://bolt.new):
+
+- 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.
+- Save the file — the app should launch automatically.
+
+## 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
+   ```
+
+## Setup Backend
+
+### 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)).
+
+#### 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)
+
+#### 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)
+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.
+7. Push your tables to the cloud db
+   ```shell
+   npx supabase db push
+   ```
+
+### 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)
+
+> 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).
+
+1. **Get your Personal Access Token:**
+   - Go to the [PowerSync dashboard](https://powersync.journeyapps.com/)
+   - Press `Ctrl + Shift + P` (or `Cmd + Shift + P` on Mac)
+   - Search for "Create Personal Access Token"
+   - Give it "owner" policy and a descriptive label
+   - Copy the generated token
+
+2. **Initialize the CLI and authenticate:**
+   ```bash
+   npx powersync init
+   ```
+Paste your Personal Access Token when prompted.
+
+3. **Create a new PowerSync instance:**
+   ```bash
+   npx powersync instance create
+   ```
+Follow the prompts to configure:
+- Instance name (e.g., "supabase-staging")
+- Region (e.g., "EU")
+- Database connection details from your Supabase project (use the **direct connection**, not pooling)
+- When asked about Supabase auth, answer:
+   - `? Are you using Supabase auth? Yes`
+   - `? Do you want to add audiences? No`
+
+4. **Deploy sync rules:**
+   ```bash
+   npx powersync instance sync-rules deploy -f sync-rules.yaml
+   ```
+
+> 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
+
+If you prefer using the web interface:
+
+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.
+
+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.
+
+### 3. Deploy Sync Rules
+
+#### 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.

database.pgsql

@@ -0,0 +1,21 @@
+-- See our guide for more information on how to set up your Supabase database: 
+-- https://docs.powersync.com/integration-guides/supabase-+-powersync#supabase-powersync
+
+CREATE TABLE counters
+(
+    id TEXT PRIMARY KEY,
+    count INTEGER NOT NULL DEFAULT 0,
+    owner_id TEXT NOT NULL,
+    created_at TIMESTAMP NOT NULL
+);
+
+-- Create a role/user with replication privileges for PowerSync
+CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'myhighlyrandompassword';
+-- Set up permissions for the newly created role
+-- Read-only (SELECT) access is required
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;
+
+-- Create a publication to replicate tables.
+-- Specify a subset of tables to replicate if required.
+-- NOTE: this must be named "powersync" at the moment
+CREATE PUBLICATION powersync FOR ALL TABLES;