Refactor bootstrap+sandbox into "task" framework

.circleci/config.yml

@@ -88,19 +88,11 @@ jobs:
             - build-yarn-2-cache-v3--{{ checksum "code/yarn.lock" }}
       - run:
           name: Install dependencies
-          command: |
-            cd code
-            yarn install --immutable
-      - run:
-          name: Install script dependencies
-          command: |
-            cd scripts
-            yarn install --immutable
+          command: yarn install --immutable
       - run:
           name: Bootstrap
           command: |
-            cd code
-            yarn bootstrap --build
+            yarn task --task compile --start-from=auto --no-link --debug
             git diff --exit-code
       - save_cache:
           name: Save Yarn cache
@@ -324,14 +316,13 @@ jobs:
           at: .
       - run:
           name: Creating Sandboxes
-          command: yarn task --task create --template $(yarn get-template ci create) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task sandbox --template $(yarn get-template ci create) --no-link --start-from=never --junit
       - persist_to_workspace:
           root: .
           paths:
             - sandbox
       - store_test_results:
-          path: code/test-results
+          path: test-results
   smoke-test-sandboxes:
     executor:
       class: medium+
@@ -344,10 +335,9 @@ jobs:
           at: .
       - run:
           name: Smoke Testing Sandboxes
-          command: yarn task --task smoke-test --template $(yarn get-template ci smoke-test) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task smoke-test --template $(yarn get-template ci smoke-test) --no-link --start-from=never --junit
       - store_test_results:
-          path: code/test-results
+          path: test-results
   build-sandboxes:
     executor:
       class: medium+
@@ -360,10 +350,9 @@ jobs:
           at: .
       - run:
           name: Building Sandboxes
-          command: yarn task --task build --template $(yarn get-template ci build) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task build --template $(yarn get-template ci build) --no-link --start-from=never --junit
       - store_test_results:
-          path: code/test-results
+          path: test-results
       - persist_to_workspace:
           root: .
           paths:
@@ -380,10 +369,9 @@ jobs:
           at: .
       - run:
           name: Running Test Runner
-          command: yarn task --task test-runner --template $(yarn get-template ci test-runner) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task test-runner --template $(yarn get-template ci test-runner) --no-link --start-from=never --junit
       - store_test_results:
-          path: code/test-results
+          path: test-results
   chromatic-sandboxes:
     executor:
       class: medium+
@@ -396,10 +384,9 @@ jobs:
           at: .
       - run:
           name: Running Chromatic
-          command: yarn task --task chromatic --template $(yarn get-template ci chromatic) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task chromatic --template $(yarn get-template ci chromatic) --no-link --start-from=never --junit
       - store_test_results:
-          path: code/test-results
+          path: test-results
   e2e-sandboxes:
     executor:
       class: medium+
@@ -412,10 +399,9 @@ jobs:
           at: .
       - run:
           name: Running E2E Tests
-          command: yarn task --task e2e-tests --template $(yarn get-template ci e2e-tests) --force --no-before --junit
-          working_directory: code
+          command: yarn task --task e2e-tests --template $(yarn get-template ci e2e-tests) --no-link --start-from=never --junit
       - store_test_results:
-          path: code/test-results
+          path: test-results
       - store_artifacts: # this is where playwright puts more complex stuff
           path: code/playwright-results/
           destination: playwright

.github/workflows/generate-repros-next.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Install dependencies
         run: node ./scripts/check-dependencies.js
       - name: Bootstrap Storybook libraries
-        run: yarn bootstrap --prep
+        run: yarn task --task compile --start-from=auto --no-link
         working-directory: ./code
       - name: Generate repros
         run: yarn generate-repros-next --local-registry

.github/workflows/tests-unit.yml

@@ -29,12 +29,7 @@ jobs:
         with:
           node-version: ${{ matrix.node_version }}
           cache: yarn
-      - name: install, bootstrap
-        run: |
-          cd code
-          yarn install --immutable
-          yarn bootstrap --core
+      - name: install and compile
+        run: yarn task --task compile --start-from=auto
       - name: test
-        run: |
-          cd code
-          yarn test --runInBand --ci
+        run: yarn test --runInBand --ci

.gitignore

@@ -18,4 +18,4 @@ junit.xml
 !/**/.yarn/sdks
 !/**/.yarn/versions
 /**/.pnp.*
-/yarn.lock
+!/node_modules

.yarnrc.yml

@@ -0,0 +1,3 @@
+nodeLinker: node-modules
+
+yarnPath: .yarn/releases/yarn-3.2.3.cjs

CONTRIBUTING.md

@@ -2,17 +2,33 @@
 
 - Ensure you have node version 14 installed (suggestion: v14.18.1).
 - Ensure if you are using Windows to use the Windows Subsystem for Linux (WSL).
-- Run `./bootstrap.sh` to install the dependencies, and get the repo ready to be developed on.
-- Run `yarn start` inside of the `code` directory to start the development server.
+- Run `yarn start` directory to run a basic test Storybook "sandbox".
 
-# Generating reproductions
+# Running against different sandbox templates
 
-The monorepo has a script that generates Storybook reproductions based on configurations set in the `code/lib/cli/src/repro-templates.ts` file. This makes it possible to quickly bootstrap examples with and without Storybook, for given configurations (e.g. CRA, Angular, Vue, etc.)
+The `yarn start` script will generate a Create React App TypeScript sandbox with a set of test stories inside it, as well as taking all steps required to get it running (building the various packages we need etc).
+
+You can also pick a specific template to use as your sandbox by running `yarn task`, which will prompt you to make further choices about which template you want and which task you want to run. 
+
+# Making code changes
+
+If you want to make code changes to Storybook packages while running a sandbox, you'll need to do the following:
+
+1. In a second terminal run `yarn build --watch <package-1> <package-2>` in the `code/` directory. The package names is the bit after the `@storybook/` in the published package. For instance:
+
+```bash
+cd code
+yarn build --watch react core-server api addon-docs
+```
+
+2. If you are running the sandbox in "linked" mode (the default), you should see the changes reflected on a refresh (you may need to restart it if changing server packages)
+
+3. If you are running the sandbox in "unlinked" mode you'll need to re-run the sandbox from the `publish` step to see the changes:
+
+```
+yarn task --task dev --template <your template> --start-from=publish
+```
 
-To do so:
-- Check the `code/lib/cli/src/repro-templates.ts` if you want to see what will be generated
-- Run `./generate-repros.sh`
-- Check the result in the `repros` directory
 
 # Contributing to Storybook
 

README.md

@@ -182,9 +182,13 @@ Looking for a first issue to tackle?
 
 Storybook is organized as a monorepo using [Lerna](https://lerna.js.org/). Useful scripts include:
 
-#### `./bootstrap.sh`
+#### `yarn start`
 
-> Installs package dependencies and links packages together - using lerna
+> Runs a sandbox template storybook with test stories
+
+#### `yarn task`
+
+> As above, but gives you options to customize the sandbox
 
 #### `yarn lint`
 

code/lib/blocks/README.md

@@ -7,7 +7,7 @@ Portable documentation components for building design systems in Storybook.
 To bootstrap, in the monorepo root:
 
 ```sh
-yarn && yarn bootstrap --core
+yarn start
 ```
 
 To develop this package, in the monorepo root:

code/package.json

@@ -53,7 +53,6 @@
   },
   "scripts": {
     "await-serve-storybooks": "wait-on http://localhost:8001",
-    "bootstrap": "node ../scripts/bootstrap.js",
     "build": "NODE_ENV=production node ../scripts/build-package.js",
     "build-storybooks": "cross-env STORYBOOK_DISPLAY_WARNING=true DISPLAY_WARNING=true node -r esm ../scripts/build-storybooks.js",
     "changelog": "pr-log --sloppy --cherry-pick",
@@ -64,7 +63,6 @@
     "danger": "danger",
     "generate-repros": "zx ../scripts/repros-generator/index.mjs",
     "generate-repros-next": "ts-node ../scripts/next-repro-generators/generate-repros.ts",
-    "get-template": "ts-node ../scripts/get-template.ts",
     "github-release": "github-release-from-changelog",
     "linear-export": "ts-node --project=../scripts/tsconfig.json ../scripts/linear-export.ts",
     "lint": "yarn lint:js && yarn lint:md",
@@ -84,7 +82,6 @@
     "serve-storybooks": "http-server ./built-storybooks -p 8001",
     "smoketest-storybooks": "cross-env STORYBOOK_DISPLAY_WARNING=true DISPLAY_WARNING=true node -r esm ../scripts/smoketest-storybooks.js",
     "start": "yarn workspace official-storybook storybook --no-manager-cache",
-    "task": "ts-node ../scripts/task.ts",
     "test": "NODE_OPTIONS=--max_old_space_size=4096 jest --config ./jest.config.js",
     "test-puppeteer": "jest --projects examples/official-storybook/storyshots-puppeteer",
     "test:cli": "npm --prefix lib/cli run test",

docs/contribute/code.md

@@ -17,43 +17,52 @@ Start by [forking](https://docs.github.com/en/github/getting-started-with-github
 git clone https://github.com/your-username/storybook.git
 ```
 
-In the root directory, run the following command:
+## Run your first sandbox
+
+Storybook development happens in a set of *sandboxes* which are templated Storybook environments corresponding to different user setups. Within each sandbox, we inject a set of generalized stories that allow us to test core features and addons in all such environments.
+
+To run an sandbox locally, you can use the `start` command:
 
 ```shell
-./bootstrap.sh --core
+yarn start
 ```
 
-This will install dependencies in both `scripts` and `code` directories, as well as build all the necessary packages for Storybook to run.
+That will install the required prerequisites, build the code, create and link and example for a Create React App setup, and start the storybook server.
 
-## Run tests & examples
+If all goes well you should see the sandbox running.
 
-Once you've completed the [initial setup](#initial-setup), you should have a fully functional version of Storybook built on your local machine. Before making any code changes, it's helpful to verify that everything is working as it should. More specifically, the test suite and examples.
+![Storybook Sandbox Running](./storybook-cra-sandbox.png)
 
-Run the following command to execute the tests:
+## Running a different sandbox template
 
-```shell
-yarn test
-```
+The `start` command runs a CRA template, but there are many others you can use if you want to work on a different renderer or framework.
 
-Once the tests finish, check if the examples are working with the following commands:
+To get started, run the `yarn task` command; it will prompt you with a series of questions to figure out what you are trying to do. Once you've made a selection it will provide a set of options that you can use to run the same command again.
 
 ```shell
-cd examples/react-ts && yarn storybook
+yarn task
 ```
 
 <div class="aside">
-💡 The Storybook monorepo contains various example projects, each corresponding to a different framework and environment, and they are commonly used as additional tooling to test new features.
+💡 The <code>yarn task</code> command takes a couple of shortcuts for development that could catch you out if you change branches: you may need to rerun the <code>install</code> and <code>compile</code> tasks. You can do that with <code>--start-from=install</code></li>.
 </div>
 
-If everything is working as it should, you should see the `examples/react-ts` Storybook running.
 
-![Example Storybook running](./storybook-cra-examples-optimized.png)
+## Running tests
+
+Once you've run your [first sandbox](#run-your-first-sandbox), you should have a fully functional version of Storybook built on your local machine. Before making any code changes, it's helpful to verify that everything is working as it should. More specifically, the test suite.
+
+Run the following command to execute the tests:
+
+```shell
+yarn test
+```
 
 ## Start developing
 
-Now that you've [verified your setup](#sanity-check), it's time to jump into code. The simplest way to do this is to run one of the examples in one terminal window and the interactive build process in a separate terminal.
+Now that you've [verified your setup](#sanity-check), it's time to jump into code. The simplest way to do this is to run one of the sandboxes in one terminal window and the interactive build process in a separate terminal.
 
-Assuming you're still running the `examples/react-ts` from the previous step, open a new terminal and navigate to the root of the Storybook monorepo. Then, create a new branch with the following command:
+Assuming you're still running the Create React App sandbox from `yarn start`, open a new terminal and navigate to the `code/` dir of the Storybook monorepo. Then, create a new branch with the following command:
 
 ```shell
 git checkout -b my-first-storybook-contribution
@@ -87,11 +96,11 @@ When you're done coding, add documentation and tests as appropriate. That simpli
 
 ### Add stories
 
-Adding a story or set of stories to our suite of example apps helps you test your work.
+Adding a story or set of stories to our suite of generic stories helps you test your work.
 
-If you're modifying part of Storybook's core, or one of the essential addons, there's probably an existing set of stories in the [`official-storybook`](../../examples/official-storybook) that documents how the feature is supposed to work. Add your stories there.
+If you're modifying part of Storybook's core, or one of the essential addons, there's probably an existing set of stories in that addons `template/stories` folder that documents how the feature is supposed to work. Add your stories there.
 
-If you're modifying something related to a specific framework, the framework will have its own examples in the monorepo. For instance, [`examples/vue-kitchen-sink`](../../examples/vue-kitchen-sink) is a natural place to add stories for `@storybook/vue` while [`examples/angular-cli`](../../examples/angular-cli) is the place for `@storybook/angular`.
+If you're modifying something related to a specific renderer, the renderer will have its own template stories.
 
 ### Add tests
 
@@ -105,11 +114,13 @@ Unit tests ensure that Storybook doesn't break accidentally. If your code can re
 
 ### End-to-end tests (e2e)
 
-Storybook's monorepo is set up to rely on end-to-end testing with [Cypress](https://www.cypress.io/) during CI. To help with testing, we encourage running this test suite before submitting your contribution. Detailed below are some steps you can take:
+Storybook's monorepo is set up to rely on end-to-end testing with [Playwright](https://playwright.dev) during CI. To help with testing, we encourage running this test suite before submitting your contribution. 
 
-1. Ensure you have Storybook successfully built in your local branch (i.e., run `yarn bootstrap --core`)
-2. Open a terminal and run `yarn local-registry --port 6001 --open --publish` to publish Storybook's packages into a local registry.
-3. In a second terminal, set up a reproduction using the local registry and run the Cypress tests with `yarn test:e2e-framework`.
+To run a e2e test against a sandbox, you can use the `e2e-tests` task:
+
+```shell
+yarn task --task e2e-tests --template=<template> --start-from=auto
+```
 
 ## Submit a pull request
 
@@ -136,6 +147,23 @@ If your contribution focuses on a bugfix and you want it featured in the next st
 - [Sync a fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/syncing-a-fork)
 - [Merge an upstream repository into your fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/merging-an-upstream-repository-into-your-fork)
 
+### Reproducing job failures
+
+If one of your CI jobs fails, it will print a message explaining how to reproduce the task locally. Typically that involves running the task against the right template:
+
+```shell
+yarn task --task e2e-tests --template=cra-default-ts --start-from=install
+```
+
+Typically it is a good idea to start from the `install` task to ensure your local code is completely up to date. If you reproduce the failure, you can try and make fixes, [compile them](#start-developing) with `build`, then rerun the task with `--start-from=auto`.
+
+ <div class="aside">
+
+<p>💡 The default instructions run the code "linked" which means built changes to Storybook code will be reflected in the sandbox right away (the next time you run the task). However CI runs in "unlinked" mode, which in rare cases will behave differently.</p>
+
+<p>If you are having trouble reproducing, try adding the <code>--no-link</code> flag. If you need to do that, you'll need to <code>--start-from=compile</code> after each code change.
+</div>
+
 ## How to work with reproductions
 
 We encourage bug reports to include reproductions. In the same way that it's possible to [develop interactively](#start-developing) against example projects in the monorepo, it's also possible to develop against a reproduction repository.

netlify.toml

@@ -1,6 +1,6 @@
 [build]
   publish = "code/built-storybooks"
-  command = "./bootstrap.sh --core && cd code && yarn build-storybooks --all"
+  command = "yarn --task compile --start-from=auto --no-link && yarn build-storybooks --all"
 [build.environment]
   NODE_VERSION = "14"
   YARN_VERSION = "1.22.10"