theatre/ecosystem-tests/README.md

Ecosystem tests

Inspired by the #help channel on our Discord we collect examples for including Theatre.js in project that use different tools (parcel, Next.js, vanilla Rollup, etc...) to build them in the CI (these are the ecosystem tests).

The currently tested setups

setup	tools	package.json
ecosystem-tests/create-react-app	create-react-app, r3f extension	link

Testing the configurations locally

# clean existing build artifacts
yarn clean
# this will build all packages, publish them to yalc, link them to each setup, and run the `yarn build` command on that setup
yarn test:ecosystem

After running the above, you can also start the dev server of each setup to try it manually:

cd ecosystem-tests/[setup-name]
yarn start

Adding a new setup

If you wish to test a new setup (say Vite, or cool-new-bundler), here is how to do it:

1. Build the monorepo packages and publish them to the local npm registry, yalc.

   cd /path/to/theatre-monorepo
   # build all the packages
   yarn build
   # publish them to yalc (the local npm registry)
   zx scripts/publish-to-yalc.mjs
   

2. Start your new setup in a directory outside of the monorepo

   # start a project outside the monorepo we'll copy it in later
   cd /path/---------outside---------/theatre-monorepo
   # make a new setup folder
   mkdir new-setup .
   cd new-setup
   

3. Bootstrap your setup using npm, yarn, or other bootstrapping scripts (like npx create-react-app)

   npm init --yes
   

4. Make sure there is a yarn.lock or package-lock.json file in this directory. Otherwise, when we move it back into the monorepo, yarn will complain that this package is not listed in the monorepo as a workspace.

   touch yarn.lock
   

5. Copy the new directory back to the monorepo and cd into it

   cp -r ./path/---------outside---------/theatre-monorepo/new-setup /path/to/theatre/monorepo/build-tests/new-setup
   cd /path/to/theatre/monorepo/build-tests/new-setup
   

6. Let yarn/npm run an install

   yarn install
   

7. Install @theatre/core and @theatre/studio, and possibly @theatre/r3f from the local registry:

   npx yalc link @theatre/core @theatre/studio @theatre/r3f
   

8. Copy the source (src/*) of one of the other setups into new-setup so you don't have to start from scratch.

9. Make sure that you add a yarn build script to new-setup/package.json, because it will be used to build the setup in the CI.

10. Test your setup by running its dev server or doing a build

    yarn start
    

Gotchas Some bundlers like webpack are not configured to work well with yarn workspaces by default. For example, the webpack config of create-react-app, tries to look up the node_modules chain to find missing dependencies, which is not a behavior that we want in build-tests setups. So if a setup doesn't work, try running it outside the monorepo to see if being in the monorepo is what's causing it to fail.

Feel free to check out the existing setups in ecosystem-tests if you get stuck.