Allow specifiying a path to Histoire config file (or parent directory)

[clowNay]

Describe the bug

I run in to several issues with the following directory structure.

<root>
    <playground>
        app.vue
        nuxt.config.ts
        histoire.config.ts
    </playground>
    package.json
    ...etc
</root>

Error while collecting story /Users/andreasquist/Sites/ui/playground/components/UI-Alert.story.vue:
Error: Failed to parse source for import analysis because the content contains invalid JS syntax. Install @vitejs/plugin-vue to handle .vue files.
    at formatError (/Users/andreasquist/Sites/ui/node_modules/vite/dist/node/chunks/dep-8f5c9290.js:39055:46)
    at TransformContext.error (/Users/andreasquist/Sites/ui/node_modules/vite/dist/node/chunks/dep-8f5c9290.js:39051:19)
    at TransformContext.transform (/Users/andreasquist/Sites/ui/node_modules/vite/dist/node/chunks/dep-8f5c9290.js:58269:22)
    at async Object.transform (/Users/andreasquist/Sites/ui/node_modules/vite/dist/node/chunks/dep-8f5c9290.js:39292:30)
    at async doTransform (/Users/andreasquist/Sites/ui/node_modules/vite/dist/node/chunks/dep-8f5c9290.js:50012:29)

After that I moved the histoire.config.ts to the <root> and then it worked. Why does it need to be in the root folder?

Reproduction

Move histoire.config.file to folder https://stackblitz.com/edit/nuxt3-histoire

System Info

System:
    OS: macOS 12.3.1
    CPU: (16) x64 Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz
    Memory: 22.14 MB / 32.00 GB
    Shell: 5.8 - /bin/zsh
  Binaries:
    Node: 16.13.0 - /usr/local/bin/node
    Yarn: 1.22.10 - /usr/local/bin/yarn
    npm: 8.1.0 - /usr/local/bin/npm
    Watchman: 2022.03.21.00 - /usr/local/bin/watchman
  Browsers:
    Chrome: 103.0.5060.53
    Firefox: 89.0.2
    Safari: 15.4

Used Package Manager

npm

Validations

• [X] Follow our Code of Conduct
• [X] Read the Contributing Guidelines.
• [X] Read the docs.
• [X] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• [X] Check that this is a concrete bug. For Q&A open a GitHub Discussion.
• [X] The provided reproduction is a minimal reproducible example of the bug.

[nozomuikuta]

@clowNay

Currently, Histoire looks for its config file(s) only at the current working directory (i.e. usually project root).

For example, when you run histoire dev command as in your reproduction link:

https://github.com/histoire-dev/histoire/blob/a760adf3a1997852bbb35b88e1aae4609401fb2e/packages/histoire/src/node/bin.ts#L15-L21

https://github.com/histoire-dev/histoire/blob/a760adf3a1997852bbb35b88e1aae4609401fb2e/packages/histoire/src/node/commands/dev.ts#L49

https://github.com/histoire-dev/histoire/blob/2fb86a248902246eb7d1a1255d3281439c4ad105/packages/histoire/src/node/config.ts#L282-L291

If you want to change this behavior, it would be a feature request.

[clowNay]

@NozomuIkuta I think that behaviour should be changed or at least provide a way of defining where config file is located with an argument.

[nozomuikuta]

For you and authors to design the feature in more detail, here are information about how Histoire related tools handle config file.

Vite

Histoire is Vite-powoered (or its wrapper), so aligning API with it would be reasonable and intuitive.

Vite CLI provides -c, --config <file> option, which is passed to configFile JavaScript API.

Refs

• https://vitejs.dev/config/
• /packages/vite/src/node/cli.ts

Storybook

When it comes to "story", it's worth mentioning Storybook. Storybook CLI (i.e. start-storybook and build-storybook) provides -c, --config-dir [dir-name] option, where [dir-name] represents a path to directory where Storybook configs are located.

As far as I know, Storybook doesn't provide JavaScript API to run it.

Refs

• https://storybook.js.org/docs/react/api/cli-options

Ladle

Ladle is an alternative to Storybook and is referred to in Histoire README.

Ladle CLI also provides --config [string] option, where [string] represents a path to directory where Ladle configs are located. --config option is passed to serve function as config option internally.

While serve function is exported as a JavaSript API, there seems to be no explanation about it in documentation but in the source code.

Refs

• https://ladle.dev/docs/cli
• /packages/ladle/lib/cli/cli.js
• /packages/ladle/lib/cli/serve.js
• /packages/ladle/lib/shared/types.ts

Summary

• All the tools above have it in common how they give a name to such option to specify configuration file.
• If a tool require a dedicated directory to store related files, such option expects path to a directory, otherwise to a file
• If a tool provides JavaScript API, CLI option(s) are supposed to be used to override options passed to JavaScript API at runtime

---

IMO, -c, --config option like Vite looks nice to me, and since Histoire doesn't require a dedicated directory such as .ladle at the moment, the option should accept a path to a configuration file.