Add create-yorkie-app (#690)

Provides CLI starter kit to allow npm users to conveniently scaffold
yorkie-based cooperative apps

---------

Co-authored-by: se030 <[email protected]>

.github/workflows/create-yorkie-app-publish.yml

@@ -0,0 +1,31 @@
+name: create-yorkie-app-publish
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - tools/create-yorkie-app/**
+      - examples/**
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v2
+      - name: Setup Node 🔧
+        uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: package-lock.json
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install
+      - run: cd tools/create-yorkie-app && npm run build
+      - run: cd tools/create-yorkie-app && npm publish --provenance
+        continue-on-error: true
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

examples/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the general guides for contribution.
+
+## Keeping create-yorkie-app in sync with examples
+
+When adding a new example, you have to update create-yorkie-app's [frameworks.ts](../tools//create-yorkie-app/frameworks.ts).
+
+Add FrameworkVariant to the variants array under appropriate category like:
+
+```js
+export const FRAMEWORKS: Array<Framework> = [
+  {
+    name: 'vanilla',
+    display: 'Vanilla',
+    color: yellow,
+    variants: [
+      {
+        name: 'vanilla-codemirror6',
+        display: 'codemirror',
+      },
+      {
+        name: 'vanilla-quill',
+        display: 'quill',
+      },
+      {
+        name: 'profile-stack',
+        display: 'profile-stack',
+      },
+      // Your yorkie example in Vanilla JS
+      {
+        name: 'directory-name',
+        display: 'display-name',
+      },
+    ],
+  },
+  // ...
+];
+```

package.json

@@ -11,7 +11,8 @@
     "build": "webpack --config ./config/webpack.config.js && npm run api-report && npm run prune",
     "build:proto": "protoc -I=./src/api --js_out=import_style=commonjs:./src/api --grpc-web_out=import_style=commonjs+dts,mode=grpcwebtext:./src/api ./src/api/yorkie/v1/*.proto",
     "build:docs": "npm run predoc && api-documenter markdown --input temp --output docs",
-    "build:examples": "npm run build --workspaces",
+    "build:examples": "npm run build --workspace examples",
+    "build:create-yorkie-app": "npm run build --workspace create-yorkie-app",
     "build:ghpages": "mkdir -p ghpages/examples && cp -r docs ghpages/api-reference && find examples -name 'dist' -type d -exec sh -c 'cp -r {} ghpages/examples/$(basename $(dirname {}))' \\;",
     "api-report": "api-extractor run --local --verbose --config ./config/api-extractor.json",
     "prune": "ts-node-script ./scripts/prune-dts.ts --input ./dist/yorkie-js-sdk.d.ts --output ./dist/yorkie-js-sdk.d.ts",
@@ -94,6 +95,7 @@
     }
   },
   "workspaces": [
-    "examples/*"
+    "examples/*",
+    "tools/*"
   ]
 }

tools/README.md

@@ -0,0 +1,5 @@
+# Tools
+
+This directory contains tools for yorkie-js-sdk.
+
+For usage, refer to the README.md of each project.

tools/create-yorkie-app/.env

@@ -0,0 +1,2 @@
+VITE_YORKIE_API_ADDR='https://api.yorkie.dev'
+VITE_YORKIE_API_KEY=

tools/create-yorkie-app/MAINTAINING.md

@@ -0,0 +1,33 @@
+# Maintaining create-yorkie-app
+
+This package is an automated tool to scaffold an example project that shows practical usage of yorkie-js-sdk.
+
+```bash
+.
+├── MAINTAINING.md
+├── README.md
+├── frameworks.ts   # abstract data object representing examples/ directory
+├── index.ts        # main script
+├── package.json
+├── tsconfig.json
+└── webpack.config.js
+```
+
+## Adding a New Example
+
+Add information about your new example in [frameworks.ts](https://github.com/yorkie-team/yorkie-js-sdk/blob/main/tools/create-yorkie-app/frameworks.ts).
+
+Choose or create an appropriate category (e.g. vanilla, react, nextjs, vue, ...) and add an object like below to variants array.
+
+```ts
+{
+  name: directory_name,
+  display: displayed_name_in_prompt
+}
+```
+
+## Publishing a New Version
+
+Update the version in [package.json](https://github.com/yorkie-team/yorkie-js-sdk/blob/main/tools/create-yorkie-app/package.json#L3).
+
+Publication will be done via [create-yorkie-app-publish.yml](https://github.com/yorkie-team/yorkie-js-sdk/blob/main/.github/workflows/create-yorkie-app-publish.yml) when changes are pushed into main branch.

tools/create-yorkie-app/README.md

@@ -0,0 +1,30 @@
+# create-yorkie-app
+
+## Usage
+
+You can scaffold yorkie-js-sdk examples by:
+
+```bash
+$ npx create-yorkie-app
+```
+
+The examples have own local dependencies. So you should install dependencies before running examples.
+
+```bash
+# In the directory of the example.
+$ npm install
+```
+
+Then you can run the examples.
+
+```bash
+# In the directory of the example.
+$ npm run dev
+```
+
+Open the browser and go to the URL that is printed in the terminal.
+
+## Note
+
+Yorkie API key or local server is necessary to run each example.
+You can create and manage your projects and API keys at [Yorkie Dashboard](https://yorkie.dev/dashboard). If you want to configure your own server, refer to [this README](../../examples/README.md).

tools/create-yorkie-app/frameworks.ts

@@ -0,0 +1,87 @@
+import { cyan, lightGreen, reset, yellow } from 'kolorist';
+
+/**
+ * @see https://github.com/marvinhagemeister/kolorist#readme
+ */
+type ColorFunc = (str: string | number) => string;
+
+export type Framework = {
+  name: string;
+  display: string;
+  color: ColorFunc;
+  variants: Array<FrameworkVariant>;
+};
+
+type FrameworkVariant = {
+  /**
+   * directory name of the example
+   */
+  name: string;
+  /**
+   * display name (in prompt) of the example
+   */
+  display: string;
+};
+
+export const FRAMEWORKS: Array<Framework> = [
+  {
+    name: 'vanilla',
+    display: 'Vanilla',
+    color: yellow,
+    variants: [
+      {
+        name: 'vanilla-codemirror6',
+        display: 'codemirror',
+      },
+      {
+        name: 'vanilla-quill',
+        display: 'quill',
+      },
+      {
+        name: 'profile-stack',
+        display: 'profile-stack',
+      },
+    ],
+  },
+  {
+    name: 'react',
+    display: 'React',
+    color: cyan,
+    variants: [
+      {
+        name: 'react-tldraw',
+        display: 'tldraw',
+      },
+      {
+        name: 'react-todomvc',
+        display: 'todomvc',
+      },
+      {
+        name: 'simultaneous-cursors',
+        display: 'simultaneous-cursors',
+      },
+    ],
+  },
+  {
+    name: 'nextjs',
+    display: 'Next.js',
+    color: reset,
+    variants: [
+      {
+        name: 'nextjs-scheduler',
+        display: 'scheduler',
+      },
+    ],
+  },
+  {
+    name: 'vue',
+    display: 'Vue',
+    color: lightGreen,
+    variants: [
+      {
+        name: 'vuejs-kanban',
+        display: 'kanban',
+      },
+    ],
+  },
+];