build-storybook --docs has no effect

[kylegach]

Describe the bug

The --docs flag to the build-storybook CLI has no discernible effect (see docs). The flag (when combined with --no-manager-cache) does work with start-storybook. Confirmed on 6.3.7 and 6.4.0-alpha.32.

To Reproduce

Repro repo: https://github.com/kylegach/build-storybook-docs-mode

I also published the build result to GH Pages: https://kylegach.github.io/build-storybook-docs-mode/

1. Add "build-storybook:docs": "build-storybook -s public -o docs --docs" to package.json's "scripts"
2. (Literally no other changes)
3. Run yarn build-storybook:docs
4. Confirm that the result is the same as yarn build-storybook

System

Environment Info

System:
    OS: macOS Mojave 10.14.6
    CPU: (12) x64 Intel(R) Core(TM) i7-8850H CPU @ 2.60GHz
  Binaries:
    Node: 14.16.0 - ~/.nvm/versions/node/v14.16.0/bin/node
    Yarn: 3.0.1 - ~/.yarn/bin/yarn
    npm: 6.14.11 - ~/.nvm/versions/node/v14.16.0/bin/npm
  Browsers:
    Chrome: 89.0.4389.128
    Firefox: 88.0.1
    Safari: 14.1.1
  npmPackages:
    @storybook/addon-actions: ^6.4.0-alpha.32 => 6.4.0-alpha.32
    @storybook/addon-docs: ^6.4.0-alpha.32 => 6.4.0-alpha.32
    @storybook/addon-essentials: ^6.4.0-alpha.32 => 6.4.0-alpha.32
    @storybook/addon-links: ^6.4.0-alpha.32 => 6.4.0-alpha.32
    @storybook/node-logger: ^6.4.0-alpha.32 => 6.4.0-alpha.32
    @storybook/preset-create-react-app: ^3.2.0 => 3.2.0
    @storybook/react: ^6.4.0-alpha.32 => 6.4.0-alpha.32

Additional context

npx sb@next repro

✔ 🌈 Select the repro framework › react
✔ 📝 Select the repro base template › cra
✔ Enter the output directory … build-storybook-docs-mode
🏃 Running cra into /Users/kg666261/projects/build-storybook-docs-mode

🏃 Starting for cra latest

{
  name: 'cra',
  version: 'latest',
  appName: 'build-storybook-docs-mode',
  creationPath: '/Users/kg666261/projects',
  cwd: '/Users/kg666261/projects/build-storybook-docs-mode',
  e2e: false,
  pnp: false,
  framework: 'react',
  generator: 'npx create-react-app@{{version}} {{appName}} --use-npm && cd {{appName}} && echo "FAST_REFRESH=true" > .env && echo "SKIP_PREFLIGHT_CHECK=true" > .env'
}

[shilman]

@kylegach Thanks for the repro! However, it looks like you didn't check in the .yarn directory? or perhaps it's a problem with the repro script? When I try to run I get this error:

MMBP15:build-storybook-docs-mode shilman$ yarn
internal/modules/cjs/loader.js:883
  throw err;
  ^

Error: Cannot find module '/Users/shilman/projects/testing/build-storybook-docs-mode/.yarn/releases/yarn-berry.js'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:880:15)
    at Function.Module._load (internal/modules/cjs/loader.js:725:27)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:72:12)
    at internal/main/run_main_module.js:17:47 {
  code: 'MODULE_NOT_FOUND',

[kylegach]

TIL: https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored

I was globally ignoring the entire .yarn directory (we still use yarn v1 for our projects 😅 ). I updated my config per the link above and started a fresh repro using the exact same steps as before, then I force-pushed to the repo. Same issue.

[kylegach]

Hmm... last week, I was trying a simple POC, so I started from a fresh sb init, encountered the problem, reproduced with sb@next repro, and so I then reported this issue.

But it actually functions correctly in the much more complex SB setup of my real project. Honestly, I was baffled at this issue, as I know many teams depend on the feature for their production docs. 🤷‍♂️

Feel free to close this, unless you feel it's a legitimate issue with the repro script.

[BodaThomas]

I exactly have the same error than you in my project. I'm trying to build the Storybook doc only with the build-storybook --docs command, but the output looks exactly the same than the build-storybook -s public command.

I'm using the 6.3.8 version of Storybook React.

You can find the preview of my build here: https://quizzical-davinci-04e4f0.netlify.app/

[kylemh]

Docs mode doesn't work for me on fresh projects.

# 1
npx create-react-app test

# 2
npx sb init

# 3
# Add `--docs` to added `build-storybook` script in `package.json`

# 4
npm run build-storybook

# 5
open storybook-static/index.html

[shilman]

@kylemh i just tried your repro. if you run a server it works:

npx http-server storybook-static

[kylemh]

Should it not work as a static deployment? Needing to run Storybook with a server to get access to Docs mode seems like a negative requirement, and one that's not documented.

[kylemh]

Also, any idea how I'd run this thru Vercel?

[shilman]

@kylemh Strangely, when I tried it again today it reproduces per your instructions 🤔

I've isolated the bug and am looking for a fix. It was nondeterministic because it involves caching. Specifically, we cache the manager UI when we ship Storybook. If your main.js configuration matches the default configuration, it uses the cached build, which doesn't have DOCS_MODE set. The dev server has a --no-manager-cache flag, but the production build does not.

Therefore we can either:

• Incorporate --docs into the cache busting behavior
• Add --no-manager-cache to build-storybook
• Always build the manager in production (adding ~10s to the build time)

I'm tempted to go with the last option for simplicity's sake

[shilman]

Yee-haw!! I just released https://github.com/storybookjs/storybook/releases/tag/v6.5.0-alpha.22 containing PR #17300 that references this issue. Upgrade today to the @next NPM tag to try it out!

npx sb upgrade --prerelease

Closing this issue. Please re-open if you think there's still more to do.

[shilman]

This fix in #17300 is a workaround, but I am going to close this anyway. I think the way we handle manager caching will change as part of 7.0

[kylemh]

do you want me to open a PR to recommend this flag if using --docs?

[shilman]

Ta-da!! I just released https://github.com/storybookjs/storybook/releases/tag/v6.4.14 containing PR #17300 that references this issue. Upgrade today to the @latest NPM tag to try it out!

npx sb upgrade

[kylemh]

Coming back to this one @shilman

It seems like the only way I'm able to dev and ship only docs mode is to use the --no-manager-cache, but this hurts performance. Do I have any alternative course of action?