Add files and documentation for developing example in isolated repo

Migrate pull request from: splitgraph/madatdata#21

into its own repo, using `git-filter-repo` to include only commits from
subdirectory `examples/nextjs-import-airbyte-github-export-seafowl/`

ref: https://github.com/newren/git-filter-repo

This commit adds the Yarn files necessary for running the example in
an isolated repo (as opposed to as one of multiple examples in a shared
multi-workspace `examples`), points the dependencies to `canary` versions
(which reflect versions in splitgraph/madatdata#20),
and also updates the readme with information for running in local development.

.gitignore

@@ -1,4 +1,24 @@
+# yarn ignore patterns (provided by yarn
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Swap the comments on the following lines if you don't wish to use zero-installs
+# Documentation here: https://yarnpkg.com/features/zero-installs
+#!.yarn/cache
+.pnp.*
+
+# Next.js ignore patterns (don't check in secrets, but check in test vars)
 .next
 .env.local
 .env.*.local
 !.env.test.local
+
+# We're using nodeLinker: node-modules ("traditional" setup rather than PnP/zero-install)
+node_modules
+
+# Misc
+.DS_Store

.yarnrc.yml

@@ -0,0 +1,7 @@
+enableTelemetry: false
+
+nodeLinker: node-modules
+
+npmPublishAccess: private
+
+yarnPath: .yarn/releases/yarn-3.2.1.cjs

README.md

@@ -1,26 +1,125 @@
-# End-to-End Example: Use `airbyte-github` to import GitHub repository into Splitgraph, then export it to Seafowl, via Next.js API routes
+# End-to-End Example of Splitgraph, Seafowl and Madatdata
 
-This is a full end-to-end example demonstrating importing data to Splitgraph
-(using the `airbyte-github` plugin), exporting it to Seafowl (using the
-`export-to-seafowl` plugin), and then querying it (with `DbSeafowl` and React
-hooks from `@madatdata/react`). The importers and exporting of data is triggered
-by backend API routes (e.g. the Vecel runtime), which execute in an environment
-with secrets (an `API_SECRET` for Splitgraph, and a GitHub access token for
-`airbyte-github`). The client side queries Seafowl directly by sending raw SQL
-queries in HTP requests, which is what Seafowl is ultimately designed for.
+This is a full, end-to-end example built with Next.js that uses [madatdata][madatdata-repo],
+[Splitgraph][splitgraph-home] and [Seafowl][seafowl-home]. It renders a website
+where users can import GitHub repository data into Splitgraph, and then export
+that data to Seafowl, and query it directly from the client. In doing so,
+it demonstrates:
+
+- Importing data to Splitgraph (using the `airbyte-github` madatdata plugin)
+- Exporting it to Seafowl (using the `export-to-seafowl` madatdata plugin)
+- And then querying it, at both Splitgraph DDN and `demo.seafowl.cloud`, sending
+  queries directly from the client with `@madatdata/react` and `useSql`
+
+The example uses Next.js with backend routes that call the Splitgraph API to trigger
+data import (from GitHub) and data export (to Seafowl). The client side pages query
+Seafowl and Splitgraph DDN directly by sending raw SQL queries in HTTP requests,
+which is what both Splitgraph and Seafowl are ultimately designed for.
 
 ## Try Now
 
 ### Preview Immediately
 
 _No signup required, just click the button!_
 
-[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/splitgraph/madatdata/tree/main/examples/nextjs-import-airbyte-github-export-seafowl?file=pages/index.tsx)
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/splitgraph/demo-github-analytics/tree/main?file=pages/index.tsx)
 
-[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/splitgraph/madatdata/main/examples/nextjs-import-airbyte-github-export-seafowl?file=pages/index.tsx&hardReloadOnChange=true&startScript=dev&node=16&port=3000)
+[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/splitgraph/demo-github-analytics/main?file=pages/index.tsx&hardReloadOnChange=true&startScript=dev&node=16&port=3000)
 
 ### Or, deploy to Vercel (signup required)
 
 _Signup, fork the repo, and import it_
 
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/splitgraph/madatdata/tree/main/examples/nextjs-import-airbyte-github-export-seafowl&project-name=madatdata-basic-hooks&repository-name=madatdata-nextjs-basic-hooks)
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/splitgraph/demo-github-analytics/tree/main&project-name=splitgraph-seafowl-madatdata-demo&repository-name=splitgraph-seafowl-madatdata-demo)
+
+## Local Development
+
+### Make sure you're using Yarn Berry
+
+Make sure your local Yarn executable is set to Yarn Berry, so that it will read
+from `.yarnrc.yml` which will direct it to use the executable in `.yarn/releases`,
+which at the moment of writing is version `3.2.1`
+
+```bash
+yarn set version berry
+```
+
+Sanity check, `yarn --version` should be `3.2.1`:
+
+```bash
+yarn --version
+# 3.2.1
+```
+
+Also make sure you're using Node v18+:
+
+```bash
+node --version
+# v18.10.0
+```
+
+<details>
+
+<summary>Install latest `node` with `nvm`, and then install `yarn` as global package</summary>
+
+You can use `nvm` to install the latest Node version (assuming you've setup `nvm`):
+
+```bash
+nvm install
+nvm use
+npm install -g yarn
+```
+
+Note: When calling `nvm install`, you can tell it to [migrate global packages][github-nvm-migrate-global-packages]
+from your current version to the new version, which could save you from
+running `npm install -g yarn`, if for some reason this is easier for you:
+
+```bash
+nvm install --reinstall-packages-from=current
+nvm use
+```
+
+</details>
+
+### Install
+
+To install using the same versions of all packages as listed in the lockfile:
+
+```bash
+yarn install --immutable
+```
+
+### Configure
+
+You will need:
+
+- Splitgraph API key and secret ([manage credentials][splitgraph-manage-credentials])
+- Splitgraph namespace to use (it should be your username)
+- GitHub Personal Access Token ([get one][create-github-pat])
+
+The specific environment variable keys are documented via comments in the `.env.test.local`
+file, which you should copy to the (ignored) path of `.env.local`:
+
+```bash
+cp .env.test.local .env.local
+```
+
+Then, edit the `.env.local` file to insert the appropriate values for the required
+variables.
+
+### Run
+
+To run in development mode:
+
+```bash
+yarn dev
+```
+
+---
+
+[madatdata-repo]: https://github.com/splitgraph/madatdata
+[splitgraph-home]: https://www.splitgraph.com
+[seafowl-home]: https://seafowl.io
+[github-nvm-migrate-global-packages]: https://github.com/nvm-sh/nvm#migrating-global-packages-while-installing
+[splitgraph-manage-credentials]: https://www.splitgraph.com/connect/query
+[create-github-pat]: https://github.com/settings/personal-access-tokens/new

package.json

@@ -6,9 +6,10 @@
     "build": "yarn next build",
     "start": "yarn next start"
   },
+  "packageManager": "yarn@3.2.1",
   "dependencies": {
-    "@madatdata/core": "latest",
-    "@madatdata/react": "latest",
+    "@madatdata/core": "canary",
+    "@madatdata/react": "canary",
     "@observablehq/plot": "0.6.7",
     "next": "latest",
     "react": "18.2.0",