{"id":20914799,"url":"https://github.com/arrayknight/storybook-addon-headless","last_synced_at":"2025-05-13T10:31:51.595Z","repository":{"id":38172915,"uuid":"232436092","full_name":"ArrayKnight/storybook-addon-headless","owner":"ArrayKnight","description":"A Storybook addon to preview content from a headless CMS in components","archived":false,"fork":false,"pushed_at":"2023-03-07T06:45:05.000Z","size":7894,"stargazers_count":30,"open_issues_count":16,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-18T15:49:16.573Z","etag":null,"topics":["addon","graphql","headless","headless-cms","restful","storybook","storybook-addon"],"latest_commit_sha":null,"homepage":"https://storybook-addon-headless.netlify.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ArrayKnight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ArrayKnight"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2020-01-07T23:21:42.000Z","updated_at":"2024-09-16T13:55:44.000Z","dependencies_parsed_at":"2024-06-19T09:16:52.249Z","dependency_job_id":"fec9a426-bbc7-40ed-bf34-f6f0cbdf2c35","html_url":"https://github.com/ArrayKnight/storybook-addon-headless","commit_stats":{"total_commits":146,"total_committers":2,"mean_commits":73.0,"dds":0.226027397260274,"last_synced_commit":"538e7b1ac5831398626c4bed5f615821baf34d02"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArrayKnight%2Fstorybook-addon-headless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArrayKnight%2Fstorybook-addon-headless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArrayKnight%2Fstorybook-addon-headless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArrayKnight%2Fstorybook-addon-headless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ArrayKnight","download_url":"https://codeload.github.com/ArrayKnight/storybook-addon-headless/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225205903,"owners_count":17437996,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["addon","graphql","headless","headless-cms","restful","storybook","storybook-addon"],"created_at":"2024-11-18T16:10:59.161Z","updated_at":"2024-11-18T16:11:00.563Z","avatar_url":"https://github.com/ArrayKnight.png","language":"TypeScript","funding_links":["https://github.com/sponsors/ArrayKnight"],"categories":[],"sub_categories":[],"readme":"# Storybook Addon Headless\r\n\r\nStorybook Addon Headless allows you to preview data from a headless CMS inside stories in [Storybook](https://storybook.js.org/). It supports Restful and GraphQL APIs with the help of [Axios](https://github.com/axios/axios) and [Apollo Client](https://github.com/apollographql/apollo-client) respectively. And each query can handle variables which are validated using [Ajv](https://github.com/epoberezkin/ajv).\r\n\r\n### Upgrading to v2\r\n\r\n_Dependencies **Storybook@6** and **Apollo@3** have been released!_\r\n\r\nBe aware of the change to Storybook's story parameters, StoryContext (where `data` is accessed) is now the second parameter.\r\n\r\n## Examples\r\n\r\nCheck out examples and detailed documentation:\r\n\r\n-   [https://storybook-addon-headless.netlify.com/?path=/story/examples](https://storybook-addon-headless.netlify.com/?path=/story/examples)\r\n-   [https://github.com/ArrayKnight/storybook-addon-headless/tree/master/src/examples](https://github.com/ArrayKnight/storybook-addon-headless/tree/master/src/examples)\r\n-   [https://medium.com/arrayknight/how-to-get-real-data-into-storybook-8915f5371b6](https://medium.com/arrayknight/how-to-get-real-data-into-storybook-8915f5371b6)\r\n\r\n|                                                  Headless                                                  |                                                  Story                                                  |\r\n| :--------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------: |\r\n| ![](https://raw.githubusercontent.com/ArrayKnight/storybook-addon-headless/master/src/assets/headless.png) | ![](https://raw.githubusercontent.com/ArrayKnight/storybook-addon-headless/master/src/assets/story.png) |\r\n\r\n## Getting Started\r\n\r\n#### Install\r\n\r\nFirst of all, you need to install Headless into your project as a dev dependency.\r\n\r\n```sh\r\nnpm install --save-dev storybook-addon-headless\r\n```\r\n\r\n#### Register\r\n\r\nThen, configure it as an addon by adding it to your `addons.js` file (located in the Storybook config directory).\r\n\r\n```js\r\nimport 'storybook-addon-headless'\r\n```\r\n\r\nOr to the `addons` parameter in your `main.js` file (located in the Storybook config directory).\r\n\r\n```js\r\nmodule.exports = {\r\n    addons: ['storybook-addon-headless'],\r\n    ...,\r\n}\r\n```\r\n\r\n#### Decorate\r\n\r\nDepending on the need of your project, you can either, add the `withHeadless` decorator:\r\n\r\n-   Globally in `config.js` via `addDecorator(withHeadless({ ... }))`\r\n-   Locally via `storiesOf('Name', module).addDecorator(withHeadless({ ... }))`\r\n-   Locally to a story via CSF:\r\n\r\n```js\r\nexport default {\r\n    ...,\r\n    decorators: [withHeadless({ ... })],\r\n    ...,\r\n}\r\n```\r\n\r\nYou can find options documented as [HeadlessOptions](https://github.com/ArrayKnight/storybook-addon-headless/blob/master/src/types/options.ts) and on the [documentation site](https://storybook-addon-headless.netlify.com/?path=/story/options--page).\r\n\r\n##### [Options](https://storybook-addon-headless.netlify.com/?path=/story/options--page)\r\n\r\n```js\r\n{\r\n    graphql?: GraphQLOptionsTypes\r\n    restful?: RestfulOptionsTypes\r\n    jsonDark?: ReactJsonViewThemeKey\r\n    jsonLight?: ReactJsonViewThemeKey\r\n}\r\n```\r\n\r\nUnder the covers, this addon uses Axios for Restful queries and Apollo Client for GraphQL queries. These configs are optional, though you'll likely want to use one or both. The configs will also be merged with the optional configs being passed through the parameters.\r\n\r\n#### [Parameters](https://storybook-addon-headless.netlify.com/?path=/story/parameters--page)\r\n\r\nParameters are added locally via:\r\n\r\n-   `storiesOf('Name', module).addParameters({ headless: { ... } })`\r\n-   `add(name, storyFn, { headless: { ... } })`\r\n-   Via CSF:\r\n\r\n```js\r\nexport default {\r\n    ...,\r\n    parameters: {\r\n        headless: { ... }\r\n    },\r\n    ...,\r\n}\r\n```\r\n\r\nYou can find parameters document as [HeadlessParameters](https://github.com/ArrayKnight/storybook-addon-headless/blob/master/src/types/parameters.ts) and on the [documentation site](https://storybook-addon-headless.netlify.com/?path=/story/parameters--page).\r\n\r\n```js\r\n{\r\n    headless: {\r\n        [name]: HeadlessParameter,\r\n        ...,\r\n    }\r\n}\r\n```\r\n\r\n`name` is the string to represent the query and data. It will be shown in the tab for the query and be the accessor on the data object in the story context.\r\n\r\n`HeadlessParameter` represents several different possible options:\r\n\r\n-   `string`: Restful URL\r\n-   `PackedDocumentNode`: A `pack`ed GraphQL Tag `DocumentNode`\r\n-   `GraphQLParameters`: [An object](https://github.com/ArrayKnight/storybook-addon-headless/blob/master/src/types/parameters.ts) with a `PackedDocumentNode` as a query and some optional parameters\r\n-   `RestfulParameters`: [An object](https://github.com/ArrayKnight/storybook-addon-headless/blob/master/src/types/parameters.ts) with a Restful URL string as a query and some optional parameters\r\n\r\nDue to the way a `DocumentNode` is converted to JSON, to maintain the original source query use the `pack` utility method.\r\n\r\n#### [Components](https://storybook-addon-headless.netlify.com/?path=/story/components--page)\r\n\r\nTo help provide a better user experience, there are Prompt and Loader helper components provided.\r\n\r\nThese components are entirely optional, but will help to direct users to the Headless tab if necessary and provide feedback about the state of active API requests.\r\n\r\nYou can find basic usage in the [examples](https://github.com/ArrayKnight/storybook-addon-headless/tree/master/src/examples).\r\n\r\n**Experimental** _(read: untested)_:\r\n\r\nThere are also two methods for those of you not using React, but wanting to use these helper components. `useHeadlessPrompt` and `useHeadlessLoader` will render the React components as standalone apps, but you must provide an HTML element reference that has been rendered and mounted by your framework of choice.\r\n\r\n### Produced @ [GenUI](https://www.genui.com/)\r\n\r\nThis addon was developed while I was employed at GenUI, a software product development firm in Seattle, WA, USA. Interested in knowing more, starting a new project or working with us? Come check us out at [https://www.genui.com/](https://www.genui.com/)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farrayknight%2Fstorybook-addon-headless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farrayknight%2Fstorybook-addon-headless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farrayknight%2Fstorybook-addon-headless/lists"}