react-cosmos/rfcs

Change requests for React Cosmos

React Cosmos RFCs

Warning Deprecated this repo in favor in favor of GitHub Discussions.

Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub pull request workflow.

Some changes though are "substantial", and we ask that these be put through a bit of a design process and produce a consensus among the React Cosmos core team.

The "RFC" (request for comments) process is intended to provide a consistent and controlled path for new features to enter the project.

Active RFC List

React Cosmos is still actively developing this process, and it will still change as more features are implemented and the community settles on specific approaches to feature development.

When to follow this process

You should consider using this process if you intend to make "substantial" changes to React Cosmos or its documentation. Some examples that would benefit from an RFC are:

• A new feature that creates new API surface area, and would require a feature flag if introduced.
• The removal of features that already shipped as part of the release channel.
• The introduction of new idiomatic usage or conventions, even if they do not include code changes to React Cosmos itself.

The RFC process is a great opportunity to get more eyeballs on your proposal before it becomes a part of a released version of React Cosmos. Quite often, even proposals that seem "obvious" can be significantly improved once a wider group of interested people have a chance to weigh in.

The RFC process can also be helpful to encourage discussions about a proposed feature as it is being designed, and incorporate important constraints into the design while it's easier to change, before the design has been fully implemented.

Some changes do not require an RFC:

• Rephrasing, reorganizing or refactoring
• Addition or removal of warnings
• Additions that strictly improve objective, numerical quality criteria (speedup, better browser support)
• Additions only likely to be noticed by other implementors-of-React Cosmos, invisible to users-of-React Cosmos.

What the process is

In short, to get a major feature added to React Cosmos, one usually first gets the RFC merged into the RFC repo as a markdown file. At that point the RFC is 'active' and may be implemented with the goal of eventual inclusion into React Cosmos.

• Fork the RFC repo http://github.com/react-cosmos/rfcs
• Copy 0000-template.md to text/0000-my-feature.md (where 'my-feature' is descriptive. Don't assign an RFC number yet).
• Fill in the RFC. Put care into the details: RFCs that do not present convincing motivation, demonstrate understanding of the impact of the design, or are disingenuous about the drawbacks or alternatives tend to be poorly-received.
• Submit a pull request. As a pull request the RFC will receive design feedback from the larger community, and the author should be prepared to revise it in response.
• Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those that don't receive any comments.
• Eventually, the team will decide whether the RFC is a candidate for inclusion in React Cosmos.
• An RFC may be rejected by the team after public discussion has settled and comments have been made summarizing the rationale for rejection. A member of the team should then close the RFCs associated pull request.
• An RFC may be accepted and a team member will merge the RFCs associated pull request, at which point the RFC will become 'active'.

The RFC life-cycle

Once an RFC becomes active, then authors may implement it and submit the feature as a pull request to the React Cosmos repo. Becoming 'active' is not a rubber stamp, and in particular still does not mean the feature will ultimately be merged; it does mean that the core team has agreed to it in principle and are amenable to merging it.

Furthermore, the fact that a given RFC has been accepted and is 'active' implies nothing about what priority is assigned to its implementation, nor whether anybody is currently working on it.

Modifications to active RFCs can be done in followup PRs. We strive to write each RFC in a manner that it will reflect the final design of the feature; but the nature of the process means that we cannot expect every merged RFC to actually reflect what the end result will be at the time of the next major release; therefore we try to keep each RFC document somewhat in sync with the feature as planned, tracking such changes via followup pull requests to the document.

Implementing an RFC

The author of an RFC is not obligated to implement it. Of course, the RFC author (like any other developer) is welcome to post an implementation for review after the RFC has been accepted.

If you are interested in working on the implementation for an 'active' RFC, but cannot determine if someone else is already working on it, feel free to ask (e.g. by leaving a comment on the associated issue).

Reviewing RFCs

Each week the team will attempt to review some set of open RFC pull requests.

React Cosmos doesn't employ full-time developers and the RFC process can be delayed in some cases. We thank you for your patience and for your contributions to React Cosmos.

React Cosmos's RFC process owes its inspiration to the React RFC process

rfcs's Issues

Ability to disable react-error-overlay

While refactoring many files one may create compile warnings across multiple files. Because react-error-overlay doesn't let you see the component/fixture you're working on until there are no errors, you can't easily iterate through files one at a time. You have to go fix all the compile errors before viewing the component you're currently working on.

You can inspect the overlay and delete it from the DOM showing the component/fixture you're working on.

Link command for Cosmos contributors

A watch command that Cosmos contributors can use to link the Cosmos monorepo to another test repository on the same machine. Basically watching for changes in packages/$pkg/dist/(**/*) and automatically copying the changed files to /path/to/test/repo/node_modules/$pkg/dist/$1.

yarn/npm link doesn't work because some Cosmos modules look up dependencies at run-time relative to where the Cosmos modules are placed.

Command would look like this:

yarn link-dist /path/to/test/repo

Synchronous dev utilities

About

The dev utilities exported from the "react-cosmos" package are great but their async implementation can make basic usage tricky or impossible.

It would be awesome if a sync version of these packages could be provided.

Here's an example of how I'm currently using getFixtureUrls. Because the function is async, there's no way to make use of test.each.

Another example is a bash script which needs the fixture urls. There's no easy way to get them because something such as this would not work due to the async implementation URLS=$(node -x "require('react-cosmos').getFixtureUrls()")

Final example, this was a hack I had to do to make a backstop config that uses fixture URLs. Synchronously, I would have just done this:

// backstop.js

module.exports = {
  // ...
  scenarios: getFixtureUrls().map((url) => ({
    // ...
  )})
}

Snapshots for manual/automated visual regression testing

What's up?

Snapshots are a really efficient way to tell if a fixture has changed from one commit to another. They are much faster than re-running an entire browser visual regression tool that requires diffing screenshots from real browsers.

However, looking at changes in snapshots is not a great experience. A lot of the time when snapshots have changed, it was intended. But that just makes it that much harder to catch when unintended changes have happened. Being able to actually visually see what the changes are is a much more reliable experience.

So what if we used snapshots for their performance, and the Cosmos UI + Browser-based visual regression tools for their feedback?

1. Take snapshots of every fixture in a project
2. Compare snapshots to discover which fixtures have "changed"
3. Highlight fixtures that have "changed" in sidebar in the the Cosmos UI
4. Allow the fixtures in the sidebar to be filtered down to just the ones that have "changed"
5. Have a button in the UI to write the updated snapshot to the file system
6. Allow the cosmos-export CLI to statically build just the fixtures that have "changed" between two commits (Useful for deploying on every PR)
7. Have a library API/CLI command for listing all the fixtures that have "changed" so that other tooling can be run on just the fixtures that have "changed".

Mkay, tell me more...

cosmos-snapshot

Re-run all of the snapshots and list the ones that have changed vs the snapshots written to the file system.

$ cosmos-snapshot
/path/to/__fixtures__/foo.tsx

cosmos-snapshot --write

Same as cosmos-snapshot but write the changed snapshots back to the file system (similar to how prettier --write or jest -u works).

$ cosmos-snapshot --write
/path/to/__fixtures__/foo.tsx (updated)

cosmos-snapshot --since <git-ref>

Instead of comparing the snapshots against the file system, test them against a git ref.

$ cosmos-snapshot --since master
/path/to/__fixtures__/foo.tsx
/path/to/__fixtures__/bar.tsx
/path/to/__fixtures__/baz.tsx

Filters

On top of being able to filter fixtures by their name or path, you should also be able to filter by changed fixtures. Here's an idea for the query syntax:

@changed
@changed(since: <git-ref>)

Note: I think it's important this has a syntax so you can use it for CLI options like below.

cosmos-export --filter <query>

Instead of exporting every fixture, export only the fixtures matching a particular filter.

$ cosmos-export --filter "@changed(since: master)"
/path/to/__fixtures__/foo.tsx
/path/to/__fixtures__/bar.tsx
/path/to/__fixtures__/baz.tsx

Implementation Note: This should not rebuild every single fixture to re-snapshot them. It should be comparing the snapshots on the file system against the ones in the git ref. This will make the export process much faster so it can be run on every commit in a CI environment in even the biggest projects.

Snapshotting Quickly

I can see that Jest Snapshots are being used today. However, running jest is a rather heavyweight way of getting the Cosmos snapshots. It would be much faster if you used some of the libraries of either Jest or AVA to take the snapshots.

Enabling scripted config files

While i totally understand the reasoning behind following restriction...

The React Cosmos config is a JSON file, so it can only host serializable values. This design decision is meant to discourage complex configuration, make it easy to embed config options into the UI, and enable visual config management in the future.

...I would love to see a way to allow JavaScript config files to be able to embed react-cosmos in enterprise environments.

In my specific use case we are normalizing building and testing across 50 independent projects in our company with a custom CLI tool. To be able to use react-cosmos in this environment I have to dynamically set the webpack configPath and rootPath inside the cosmos.config.json which is currently not possible.

I looked at the code part that is currently responsible for blocking JavaScript based config files and noticed that the JSON config gets loaded via the NodeJS require function which would automatically allow JavaScript configs that include a default export.

As I said at the very beginning, I can totally understand the intention of this restriction, yet I think the JavaScript ecosystem is way to versatile and complex to restrict tool configuration on simple JSON files. Further more popular tools like ESLint and Babel are going the hybrid approach as well to allow usage in any scenario.

I would love to hear your feedback on this proposal.

Toggle dark mode

is it possible to add a dark mode toggle?
all I need is to toggle a class name on html tag, but couldn’t figure a way of doing so.

Simple WelcomeScreen

What's up?

I am planning on using react-cosmos to demo components to non-technical members of my company and the current welcome screen that is displayed has things which they will only find confusing ("mock Redux state", "fixtures", etc).

Ideally there would be a "basic info" version of the WelcomeScreen that just had the bare minimum information required for a user to see what they need to do ("Components are listed on the left side. If you are looking for a particular component you can use the search box at the top left.").

Mkay, tell me more...

One way I can think of doing it would be to have a boolean argument in the cosmos.config.js file (showBasicWelcomeScreen: boolean) and then passing that down to the WelcomeScreen component (by way of PlaygroundOpts and the component-playground).

It may not be ideal though (parameters all over the shop being passed through everything), so understandable if you didn't to go that way.

All that being said.. I may be missing something stupidly obvious that would allow me to do the above myself. Any thoughts/pointers?

Edit in CodeSandbox button

What's up?

React-Cosmos already has an Open fixture button in dev mode, but this functionality is missed in production.

Mkay, tell me more...

I've implemented this using babel plugin with cosmos decorator already: superdispatch/web-ui#32. It's fine for now, but it's hacky and can break after internal changes in react-cosmos.

Fixture options

Follow-up to How to pass parameters to a decorator? react-cosmos/react-cosmos#1234 by @frankandrobot

Need

Cosmos provides a flexible way of creating fixture decorators, but it doesn't provide a way to parametrize decorators per fixture. This was possible in Cosmos Classic (albeit in an unsafe way), and the request has already been raised before by multiple people. There is even a channel on Slack dedicated to this issue.

The official solution for parametrizing decorators at the moment is basically to not use Cosmos decorators and use wrapper components directly in fixtures. This is not a bad solution per se, but it falls short in this situation: What if you have 100 fixtures wrapped by one decorator, and you only want to parametrize the decorator in 10 fixtures? By having to manually add a wrapper component in all fixtures, you change 100 fixtures instead of 10. Ideally, 90 fixtures would use the decorator defaults, and only the other 10 fixtures provide custom decorator params.

Solution

An optional options fixture export. This option represents "fixture options" and can be annotated with a TypeScript/Flow/etc type.

The reason why these options are called "fixture options" and not "decorator params" is because I envision these options to be also used in other places besides decorators, like in a visual regression test suite that, for example, can have its viewport configured through fixture options.

The fixture options are passed as fixtureOptions in decorator props. Currently, decorator props only contain the fixture element as children.

The examples below feature TypeScript, which is 100% optional.

Here's a Redux example, because it's possibly the most popular use case that would benefit from fixture options.

// fixtureHelpers/fixtureOptions.ts (you can put this anywhere in your codebase – only for TS users)
export type FixtureOptions = {
  reduxState: MyReduxState;
};

// cosmos.decorator.tsx
type DecoratorProps = {
  children?: ReactNode;
  fixtureOptions: FixtureOptions;
};

export default ({ children, fixtureOptions }: DecoratorProps) => {
  const { reduxState = defaultReduxState } = fixtureOptions;
  return <Provider store={configureStore(reduxState)}>{children}</Provider>;
};

// MyComponent1.fixture.tsx (uses default Redux state)
export default <MyComponent foo="bar" />;

// MyComponent2.fixture.tsx (uses custom Redux state)
export options: FixtureOptions = {
  reduxState: {
    // ...
  }
}

export default <MyComponent foo="bar" />;

---

I believe this is a feature that will have a large impact for React Cosmos users. Let me know if you have any feedback. New ideas, as well as examples of other use cases that fixture options can address are more than welcome. Thanks!

Add "template" argument permitting modifications to the page wrapper component

A feature that I occasionally used in styleguidist when documenting components in an existing codebase was the ability to add some elements or imports to the shared HTML that wrapped all the fixtures.

Arguably these components could be rewritten to not depend on global state, but having this option eased the migration path when integrating certain legacy components. I was wondering if people would be interested in having that feature in cosmos too.

https://github.com/styleguidist/react-styleguidist/blob/master/docs/Configuration.md#template

Bun.sh support

React Cosmos is one of the few component libraries that could ideally be paired with Bun.sh

• no requirement for react prop-types, webpack, vite, etc
• custom bundler integration (perfect!)

However, it currently throws when using bun to bundle cosmos fixtures.

E.g. this repo with a div as a fixture

will throw an error about isBuffer3.default is not a function

Potentially due to Bun's incomplete nodejs Buffer api

I figure there are two routes we can take

• Wait on Bun.sh to complete their buffer api
• Provide a more resilient implementation in cosmos

Documentation for React Cosmos for Vite

Hi,

I know React Cosmos isn't ready for Vite except for doing workaround. I found a nice repo from kazuma1989 ( https://github.com/kazuma1989/react-cosmos-with-vite ) and i think you guys should put it inside official docs for now.

Remove redundant folders in the sidebar

In our project we're putting every component in its own folder in which there are both the components and its fixture, e.g:

• components
  • qwiltMultiSelect
    • qwiltMultiSelect.tsx
    • qwiltMultiSelect.fixture.tsx

So if I have 2 "stories" for QwiltMultiSelect, e.g: "String Data" and "Object Data", I am getting the following the following folder structure:

So, in this case, I would be glad to get rid of the duplicate "qwiltMultiSelect" folder.

Can we have a way to remove/control these redundant folders?

Is there a way to use react-cosmos with styled-components ?

Hi !

I'm trying to use react-cosmos with my components but I'm using styled-components and obvisouly an error occur :

Cannot read property 'xxx' of undefined.

My "components look like this :

I don't know how to export my theme, Can I have a "master" components taking my fixtures as children ? And import my theme in the master component ?

"Like a ThemeProvider"

Better API for getting fixture meta data

The current getFixtureUrls method returns a list of fixture URLs (either in the RC UI or in full screen mode), but it doesn't provide other meta data like the fixture name, which is useful when creating a visual diffing tool on top of React Cosmos.

@andyrichardson proposed a return type that I think would indeed be useful:

type Fixture = {
  url: string;
  fullscreenUrl: string;
  name: string;
  location: string;
}

The existing getFixtureUrls would continue to exist for backwards compatibility, but the new one would supersede it in terms of usefulness and in the official docs. The name could be something like getFixtureMetadata, getFixtureInfo or even getFixtureUrls2, which I like because it tells the whole story: It's newer, better version of the previous function, but you can use either.

Group components in a single view

What's up?

Non-technical people have trouble navigating CP if your project has a lot of components and fixtures. Ideally they'd like to be able to see similar components grouped together on one page, or have all of the fixtures in a single page for one component.

Mkay, tell me more...

I'm thinking we have a tree structure in the left nav menu, where if you click on the directory name you'll get a page with all of the components within it rendered under a specific fixture (this could be configurable, let's say that all of your components have a base.js, this would be configured in cosmos.config.js).

In addition to that, if you click on the name of a component, you should see a view of your component rendered in all states (or a subset of them). This would also be configurable, maybe we say render 3 fixtures per component, or maybe, wait for it: specify which fixtures are the most interesting to render (effectively showcasing your component in the most interesting states).

Obviously the pain points here are going to be:

• Working on the nav menu is a bit of a pain
• Extracting the directory from the name of the components
• Rendering more than one fixture into CP at a time (what happens to modals, for example, which render on the body and take over your screen?)

There are more questions here but I'd love to hear your opinion on this, @skidding. I think it's a worthwhile investment to have this feature and it's something I've seen in other playgrounds as well, the difference being that they all require the users to write JSX, which is very difficult to maintain in the long term.

Unbundled development

Hi,

Tools like snowpack and vite make for a much faster feedback loop as they don't bundle code while on development. I'd love if react-cosmos would be made compatible with these tools. Pardon me if this is possible already with some sort of specific configuration.

Thanks in advance.

PS: react-comsos is great, thank you for your work!

Documentation for using react-cosmos with gatsby

Hi there,

I've been trying to configure react-cosmos to use in a gatsby website, with little success. I've changed the webpack config to gatsby's config, read the compilation section of the docs 10x but I'm still getting nowhere. The reality I picked Gatsby because I don't want to get involved in all the nitty details of webpack building etc. And I'm not even sure if I'm heading in the right direction.

In the docs there are examples of configuring cosmos to work with create-react-app, and next.js. It would be great if there could also be a section detailing using react-cosmos with Gatsby, with some examples.

I've tried several other component viewing libraries and failed to integrate them all (including Storybook) - so making cosmos an easy option for Gatsby users and react-cosmos would be very appealing.

Cheers

Minimum display of a component: required props

When I don't first remember how to instantiate a component, I have to look up the component to find the PropTypes property. The cosmos display just shows a blank screen.

Is there a way to display what the prop-types are/require? This would improve the workflow, and allow for more aggressive fixture making - the minute something goes wrong, instead of having to look at the console (sloooowww), I can just verify the work against the what is already presented by cosmos.

Allow fixture files and directories with the same name

What's wrong?

This is how I structure my projects:

src/Feature.tsx
src/Feature/InternalComponent1.tsx
src/Feature/InternalComponent2.tsx

With fixtures, it looks like this:

src/Feature.tsx
src/Feature.fixture.tsx
src/Feature/InternalComponent1.tsx
src/Feature/InternalComponent1.fixture.tsx
src/Feature/InternalComponent2.tsx
src/Feature/InternalComponent2.fixture.tsx

With such a structure, React Cosmos loads and displays for me the fixtures Feature/InternalComponent1 and Feature/InternalComponent2, but it doesn't display the fixture Feature. I assume that's because the other fixtures are picked up first and "block" the name Feature, preventing another fixture from being called like that.

If I rename the file from src/Feature.fixture.tsx to something else, like src/Feature_.fixture.tsx, then the fixture loads.

I can use that fact as a workaround but I would match rather have all filenames match.

User info

React Cosmos version 5.6.3, Webpack version 5.38.1.

Feature Request: Automated Fixture Error Check

What's up?

We rely on Cosmos as component library for various purposes. We push it to Github pages to show progress on various parts of the app. Some engineers even use it on a daily basis for feature development (while others rely on in-app HMR).

Once in a while, fixtures break. This sometimes happens when someone adds a new required field to a component and forgets to add it to the fixture. Other times, it's errors like You should not use <Link> outside a <Router>. It's probably most typically caused by folks that don't use Cosmos for day-to-day development.

Either way though, it'd be great to be able to catch these regressions in PRs. We were planning on writing a headless browser script that traverses the entire tree for pages that error out, but what would be even better (and faster!) was if Cosmos shipped with something along the lines of a cosmos-validate command that could tell you if a feature was broken.

Mkay, tell me more...

I'm not sure if you'd eventually end up having to automate a headless browser for this, but I'm hoping there's a programmatic way and some internals that makes it easier for you than for us.

Cosmos Export Separate Documents

What's up?

In a CI environment I might want to run other tools against all (or some) of my fixtures. This might be something like visual regression tests or maybe some scripts written with Puppeteer to do smoke testing.

In those scenarios, I probably wouldn't care very much about the Cosmos UI itself, I'd just want to have statically built pages that I could use in other tools.

pages=$(cosmos-export --pages) # or some other flag, idk
# ./path/to/built/fixture.html
# ./path/to/other/built/fixture.html

for page in "${pages}"; do
   ./scripts/run-smoke-tests-on-page "${page}"
done

Mkay, tell me more...

This could potentially be extended by other tools out of the box:

cosmos-export --pages | cosmos-browser-visual-regressions
cosmos-export --pages | cosmos-etc

Documenting components

Feature request

Do you plan realize feature for document the components, like docz?

View Source

What's up?

When statically deploying React Cosmos fixtures, it would be nice to be able to have a "View Source" button that displays the source code for the fixture within the Cosmos UI. This would make it a nicer tool for documenting component frameworks and such.

Mkay, tell me more...

Here's an example from the Atlaskit UI framework:

Users of the documentation can look at code examples right next to the rendered version of the code.

But behind the scenes this is not the raw source code, it's actually be slightly preprocessed so that the imports are rewritten to be package names instead of relative paths.

- import Badge from "../src/index.tsx"
+ import Badge from "@atlaskit/badge"

So it would be good to provide some sort of hook to allow for arbitrary preprocessing of the source file.