npm package: @preply-ds/docs
Description: > Documentation entry point.
Latest version: 0.4.2

# DS Docs (entry point)

> Documentation entry point.

## Using the Design System in your application or library?

Follow the instructions in [@preply-ds/workspace](../../README.md).

## Contributing

Reach out to [#design-system-public](https://preply.slack.com/archives/C024EAEHP6V) if you think you can help and keep an eye on [DS Confluence](https://preply.atlassian.net/wiki/spaces/DS/overview) for more docs, guides, work in progress, decisions, the works.

## CI/CD

> WIP

**Related scripts:**

- `yarn build:storybook` - static build, outputs to `dist/`.
- `yarn build:meta` - copies assets, instrumentation data, and metadata collected by [fe-tools](https://github.com/preply/apollo/blob/master/fe-tools/README.md)

## Development

You probably want to execute `yarn dev` and/or `yarn docs` in the root, as per instructions in [@preply-ds/workspace](../../README.md).

You can also execute `yarn docs` in this folder, but make sure you have first executed `yarn build` in root, or that you have the root `yarn dev` script running in the background.

### Which documentation is included in this package?

None. Homepage and DS wide capabilities are documented in [@preply-ds/docs-pages](../../support/docs-pages/README.md).

Remaining docs are co-located with the source code in [@preply-ds/web-lib](../../packages/web-lib/README.md) (components) and [@preply-ds/web-core](../../packages/web-core/README.md) (capabilities).

- `*.stories.tsx` - typically one single "canvas" story
- `*.stories.mdx` - examples, guidelines, accessibility, notes, ...

**WIP** **Note:** If you want to see live metadata on your local instance you have to follow the steps outlined in fe-tools.

## Tooling

Uses `storybook@latest` + `wepback`.

Scans for pages in the monorepo, namely in:

- [@preply-ds/docs-pages](../../support/docs-pages/README.md)
- [@preply-ds/web-lib/src/components](../../packages/web-lib/README.md)

Details about global tools and configurations in [@preply-ds/workspace](../../README.md).

## Dependencies

This package should depend only on:

- `@storybook/***` and Webpack loaders

**Do NOT add dependencies on** Preply component libraries, especially DS packages like `ds-core`, `ds-web-lib`, ...

### `webpack@4` and loaders

Storybook still ships with webpack4 but it's possible to use [webpack 5](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md).

We tried this but a series of new issues, such as this recent [gh issue](https://github.com/storybookjs/storybook/issues/15336) (Jul 2011) popped up because the plugin ecosystem is still catching up with the breaking changes.

Instead, we downgraded the css loaders [gh issue](https://stackoverflow.com/questions/68580273/type-error-this-getoptions-is-not-a-function-for-style-loader) to the latest versions that are compatible with Webpack4:

- `css-loader@5.2.6`
- `less-loader@7.3.0`
- `postcss-loader@4.2.0`
- `postcss-preset-env@6.7.0`
- `style-loader@2.0.0 `

### `styled-components@4.1.3`

Pinned to `4.1.3` to stay inline with `yarn-workspace/packages/shared`. Tried to update to latest: v5.3.1 ([releases](https://styled-components.com/releases)) but it created a fuss with hoisted deps. Not critical for this project at the moment.

## Known Issues

> WIP: Consolidate these notes with follow ups from previous epics

- We are using a [container (addons/docs)](https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/recipes.md#overwriting-docs-container) added on each MDX page because of this [issue](https://github.com/storybookjs/storybook/issues/12290).

- Rendering `<Story>` (instead of `<Canvas>`) in an MDX file causes Storybook to display each "story" in the Menu, which breaks the usability of the docs page (even more :-D). Some people have suggested to [Add an option to hide a story from the sidebar](https://github.com/storybookjs/storybook/issues/9209) for this same reason (as well as hiding stories that exist for snapshot purposes only). _Right now I can accomplish this same thing with the <Story> block but I don't want the added link on the Sidebar._

- Even actively developing a component, the Controls widget sometimes displays props that no longer exist. It's a cache issue with typescript doc gen under the hood. You will need to restart

- First line in code samples in MDX docs are always poorly indent. Just an annoying detail.

- Code samples in Canvas page shows `<StoryContextDSWeb/>` because it's being injected in each `stories.tsx` via `decorators: [story => <StoryContextDSWeb>{story()}</StoryContextDSWeb>]`. It's preferrable to have this flexibility (as opposed to registering global decorators) even if the code sample is a tad polluted (another annoying detail).

- Serialization of props to url causes [issue](https://github.com/storybookjs/storybook/issues/14508) with an ugly warning `react_devtools_backend.js: Omitted potentially unsafe URL args`.

- FIX ME! Super annoying: Scroll to top after navigating between docs pages. Apparently this [issue was fixed](https://github.com/storybookjs/storybook/issues/5598).