diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6272863..a6dd399 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,51 +1,40 @@ # Contributing to Theatre.js -## The quick version +## Development workflow -Have `node 14+` and `yarn 1.22+` installed. Then `git clone` and `yarn install`. Then `cd packages/playground` and `yarn run serve`. Happy hacking! - -## The long version - -### Prerequisites - -Make sure you have [Node](https://nodejs.org/) installed at v14.0.0+ +### Setting up the environment +Make sure you have [`node 14+`](https://nodejs.org/) installed: ```sh $ node -v > v14.0.0 ``` -and [Yarn](https://classic.yarnpkg.com/en/) at v1.22.10+. +and [`yarn 1.22+`](https://classic.yarnpkg.com/en/): ```sh $ yarn -v > 1.22.10 ``` -> **Note about Yarn v2**: This repo uses Yarn v2. You don't have to install yarn v2 globally. If you do have yarn 1.22.10+ installed, and `cd` into `/path/to/theatre`, yarn will automatically switch to v2. Read more about Yarn v2 [here](https://yarnpkg.com/). - -### Fork, Clone & Install - -Start by forking Theatre.js to your GitHub account. Then clone your fork and install dependencies: +Then clone the repo: ```sh -$ git clone git@github.com:/theatre.git +$ git clone git@github.com:AriaMinaei/theatre.git $ cd theatre +``` + +And fetch the dependencies with yarn: + +```sh $ yarn ``` -> ⚠ theatre relies on -> [yarn workspaces](https://yarnpkg.com/features/workspaces) so -> `npm install` will not work in this repository. +* Notes about Yarn: + * This project uses [yarn workspaces](https://yarnpkg.com/features/workspaces) so `npm install` will not work. + * This repo uses Yarn v2. You don't have to install yarn v2 globally. If you do have yarn 1.22.10+ on your machine, yarn will automatically switch to v2 when you `cd` into theatre. Read more about Yarn v2 [here](https://yarnpkg.com/). -Add our repo as a git remote so you can pull/rebase your fork with our latest -updates: - -```sh -$ git remote add upstream git@github.com:AriaMinaei/theatre.git -``` - -## Start hacking with `playground` +### Hacking with `playground` The quickest way to start tweaking things is to run the `playground` package. @@ -60,48 +49,130 @@ It uses a single ESBuild config to build all of the related packages in one go, Read more at [`./packages/playground/README.md`](./packages/playground/README.md). +### Hacking with `examples/` + +Other than `playground`, the [`examples/`](./examples) folder contains a few small projects that use Theatre with [parcel](https://parceljs.org), [Create react app](create-react-app.dev), and other build tools. This means that unlike `playground`, you have to build all the packages before running the examples. + +You can do that by running the `build` command at the root of the repo: + +```sh +$ yarn build +``` + +Then build any of the examples: +``` +$ cd examples/dom-cra +$ yarn start +``` + +### Running tests + +We use a single [jest](https://jestjs.io/) setup for the repo. The tests files have the `.test.ts` or `.test.tsx` extension. + +You can run the tests at the root of the repo: + +```sh +$ yarn test + +# or run them in watch mode: +$ yarn test --watch +``` + +### Type checking + +The packages in this repo have full typescript coverage, so you should be able to get diagnostics and intellisense if your editor supports typescript. + +You can also run a typecheck of the whole repo from the root: + +```sh +$ yarn typecheck + +# or in watch mode: +$ yarn typecheck --watch +``` + +* If you're using VSCode, we have a ["Typescript watch"](./.vscode/tasks.json) task for VSCode that you can use by [running](https://code.visualstudio.com/Docs/editor/tasks) "Run Task -> Typescript watch". +* If you wish to contribute code without typescript annotations, that's totally fine. We're happy to add the annotations to your PR. + +### Linting + +We're using a minimal [ESLint](https://code.visualstudio.com/Docs/editor/tasks) setup for linting. If your editor supports ESLint, you should get diagnostics as you code. You can also run the lint command from the root of the repo: + +```sh +$ yarn lint:all +``` + +Some lint rules have [autofix](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems), so you can run: + +```sh +$ yarn lint:all --fix +``` + +### Publishing to npm + +Currently all packages (except for [`@theatre/r3f`](./packages/r3f/)) share the same version number. In order to publish to npm, you can run the `release` script from the root of the repo: + +```sh +$ yarn release x.y.z # npm publish version x.y.z +$ yarn release x.y.z-dev.w # npm publish version x.y.z-dev.w and tag it as "dev" +$ yarn release x.y.z-rc.w # npm publish version x.y.z-rc.w and tag it as "rc" +``` + +### Generating API docs + +We use [API extractor](https://api-extractor.com/pages/setup/generating_docs/) to generate API docs in markdown. We put the markdown files in the [theatre-docs](https://github.com/ariaminaei/theatre-docs/) repo, which also contains the tutorials and guides. + +To generate the API docs, run the `build:api-docs` from the root of the repo: + +```sh +$ yarn build:api-docs /path/to/theatre-docs/docs/api/ # this will empty the /api folder and regenerate the markdown files +``` + ## Project structure -* `@theatre/core` – The core animation library. - * Location: [`./theatre/core`](./theatre/core) -* `@theatre/studio` – The visual editor. - * Location: [`./theatre/studio`](./theatre/studio) -* `@theatre/dataverse` – The reactive dataflow library. - * Location: [`./packages/dataverse`](./packages/dataverse) -* `@theatre/react` – Utilities for using Theatre with React. - * Location: [`./packages/react`](./packages/react) -* `@theatre/r3f` – The react-three-fiber extension. - * Location: [`./packages/r3f`](./packages/r3f) -* `playground` – The quickest way to hack on the internals of Theatre. It bundles all the related packages together with one ESBuild setup. - * Location: [`./packages/playground`](./packages/playground) -* `examples/` * A bunch of examples, using Theatre with [parcel](https://parceljs.org), [Create react app](create-react-app.dev), etc. -* `*/devEnv`: Each package may have a `devEnv` folder that holds dev-related files, like bundler configuration, lint config, etc. +The [monorepo](https://en.wikipedia.org/wiki/Monorepo) consists of: +* `@theatre/core` – The core animation library at [`./theatre/core`](./theatre/core). +* `@theatre/studio` – The visual editor at [`./theatre/studio`](./theatre/studio). +* `@theatre/dataverse` – The reactive dataflow library at [`./packages/dataverse`](./packages/dataverse). +* `@theatre/react` – Utilities for using Theatre with React at [`./packages/react`](./packages/react). +* `@theatre/r3f` – The react-three-fiber extension at [`./packages/r3f`](./packages/r3f). +* `playground` – The playground explained [above](#hacking-with-playground), located at [`./packages/playground`](./packages/playground) +* `examples/` * A bunch of [examples](#hacking-with-examples) at [./examples](./examples). -### Commands +In addition, each package may contain a `dotEnv/` folder that holds some dev-related files, like bundle configuration, lint setup, etc. -#### Root commands +## Commands These commands are available at the root workspace: ```sh # Run the playground. It's a shortcut for `cd ./playground; yarn run serve` -yarn playground +$ yarn playground # Run all the tests. -yarn test +$ yarn test # Run tests in watch mode. -yarn test --watch +$ yarn test --watch # Typecheck all the packages -yarn typecheck +$ yarn typecheck + +# Typecheck all the packages in watch mode +$ yarn typecheck --watch # Run eslint on the repo -yarn lint:all +$ yarn lint:all # Run eslint and auto fix -yarn lint:all --fix +$ yarn lint:all --fix + +# Build all the packages +$ yarn build + +# Build the api documentation +$ yarn build:api-docs /path/to/theatre-docs/docs/api/ ``` > Yarn passes all extra parameters to the internal scripts. So, for example, if you wish to run the tests in watch mode, you can run `yarn test --watch`. @@ -113,22 +184,5 @@ The libraries come bundled with typescript definitions with TSDoc comments. You Other references - [Documentation: https://docs.theatrejs.com](https://docs.theatrejs.com/getting-started/) -- [Video: Theatre.js Crash Course](https://www.youtube.com/watch?v=icR9EIS1q34) - -## Testing - -Run tests during development with `yarn test --watch` to re-run tests on file changes. - -### Examples - -Other than `playground`, the [`examples/`](./examples) folder contains a few small projects using the bundled version of the library. This means that unlike `playground`, you have to build all the packages before running the examples. - -## Releasing - -Currently all packages (except for [`@theatre/r3f`](./packages/r3f/)) share the same version number. In order to publish to npm, you can run the `release` script from the root of the repo: - -```sh -$ yarn release x.y.z # npm publish version x.y.z -$ yarn release x.y.z-dev.w # npm publish version x.y.z-dev.w and tag it as "dev" -$ yarn release x.y.z-rc.w # npm publish version x.y.z-rc.w and tag it as "rc" -``` \ No newline at end of file +- [API docs: https://docs.theatrejs.com/api/](https://docs.theatrejs.com/api/) +- [Video: Theatre.js Crash Course](https://www.youtube.com/watch?v=icR9EIS1q34) \ No newline at end of file diff --git a/README.md b/README.md index e126e0d..c0a4208 100644 --- a/README.md +++ b/README.md @@ -30,11 +30,41 @@ You can use Theatre.js to: ## Documentation and Tutorials -You can find the documentation and video tutorials [here](https://docs.theatrejs.com). +The docs are at [docs.theatrejs.com](https://docs.theatrejs.com): -## Community +* [Getting started](https://docs.theatrejs.com/getting-started/) +* [In depth guide](https://docs.theatrejs.com/in-depth/) +* [API docs](https://docs.theatrejs.com/in-depth/) +* [Extensions](https://docs.theatrejs.com/extensions/) +* [Video tutorials](https://www.youtube.com/channel/UCsp9XOCs8v2twyq5kMLzS2Q) + * [Crash course](https://www.youtube.com/watch?v=icR9EIS1q34) + * [Animating with music](https://www.youtube.com/watch?v=QoS4gMxwq_4) + * [Yuri Artiukh](https://twitter.com/akella)'s [stream](https://youtu.be/qmRqgFbNprM?t=3462) with a section on using Theatre with THREE.js + * \ -Join us on [Discord](https://discord.gg/bm9f8F9Y9N), follow the updates on [twitter](https://twitter.com/AriaMinaei) or write us an [email](mailto:hello@theatrejs.com). +## Community and support + +Join our friendly community on [Discord](https://discord.gg/bm9f8F9Y9N), follow the updates on [twitter](https://twitter.com/AriaMinaei) or write us an [email](mailto:hello@theatrejs.com). + +## Development and contributing + +If you want to change the source of Theatre, have a look at the guide [here](./CONTRIBUTING.md). + +### Proposing fixes and changes + +You can always get help with bugfixes or discuss changes with our community on [Discord](https://discord.gg/bm9f8F9Y9N), or directly open an issue on Github. + +### Helping with outstanding issues + +Feel free to chime in on any [issue](https://github.com/AriaMinaei/theatre/issues). We have also labeled some issues with ["Help wanted"](https://github.com/AriaMinaei/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) or ["Good first issue"](https://github.com/AriaMinaei/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22) if you're just getting started with the codebase. + +### Helping with documentation + +The documentation website's repo is [here](https://github.com/ariaminaei/theatre-docs/). + +### Writing/recording tutorials + +If you make tutorials or video content about Theare, tell us to showcase it here :) ## License diff --git a/package.json b/package.json index b3f94ec..fbe9fc9 100644 --- a/package.json +++ b/package.json @@ -10,6 +10,7 @@ "scripts": { "playground": "yarn workspace playground run serve", "typecheck": "yarn run build:ts", + "build": "zx scripts/build.mjs", "build:ts": "tsc --build ./devEnv/typecheck-all-projects/tsconfig.all.json", "test": "jest", "postinstall": "husky install", diff --git a/scripts/build-api-docs.mjs b/scripts/build-api-docs.mjs index 53dec2f..28ff85b 100644 --- a/scripts/build-api-docs.mjs +++ b/scripts/build-api-docs.mjs @@ -1,6 +1,11 @@ +/** + * This script generates API documentation files in the target folder. + * Usage: `$ yarn build:api-docs ` creates the .md files in . + * Example: `$ yarn build:api-docs path/to/theatre-docs/docs/api/` + * + * Usually is https://github.com/AriaMinaei/theatre-docs/tree/main/docs/api + */ import path from 'path' -import {readFileSync, writeFileSync} from 'fs' -import {keyBy} from 'lodash-es' import {parse as parseJsonC} from 'jsonc-parser' ;(async function () { // better quote function from https://github.com/google/zx/pull/167 diff --git a/scripts/build.mjs b/scripts/build.mjs new file mode 100644 index 0000000..f1a3fc2 --- /dev/null +++ b/scripts/build.mjs @@ -0,0 +1,40 @@ +/** + * Builds all the packages for production + */ + +const packagesToBuild = [ + 'theatre', + '@theatre/dataverse', + '@theatre/react', + '@theatre/browser-bundles', + '@theatre/r3f', +] + +;(async function () { + // better quote function from https://github.com/google/zx/pull/167 + $.quote = function quote(arg) { + if (/^[a-z0-9/_.-]+$/i.test(arg)) { + return arg + } + return ( + `$'` + + arg + .replace(/\\/g, '\\\\') + .replace(/'/g, "\\'") + .replace(/\f/g, '\\f') + .replace(/\n/g, '\\n') + .replace(/\r/g, '\\r') + .replace(/\t/g, '\\t') + .replace(/\v/g, '\\v') + .replace(/\0/g, '\\0') + + `'` + ) + } + + await Promise.all([ + $`yarn run buid:ts`, + ...packagesToBuild.map( + (workspace) => $`yarn workspace ${workspace} run build`, + ), + ]) +})()