{"id":15932643,"url":"https://github.com/snugug/starchart-studio","last_synced_at":"2026-06-04T16:31:40.661Z","repository":{"id":143036059,"uuid":"574714960","full_name":"Snugug/starchart-studio","owner":"Snugug","description":"Starchart Studio","archived":false,"fork":false,"pushed_at":"2023-02-23T20:12:14.000Z","size":219,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-11T06:59:48.101Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Astro","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/Snugug.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2022-12-05T23:15:07.000Z","updated_at":"2023-01-31T21:40:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"a78d2bcc-0619-467b-9dd8-fc93aaebfd2f","html_url":"https://github.com/Snugug/starchart-studio","commit_stats":{"total_commits":28,"total_committers":2,"mean_commits":14.0,"dds":0.3214285714285714,"last_synced_commit":"efb5af420855ea2ad87a519b4189af17c867237e"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Snugug/starchart-studio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snugug%2Fstarchart-studio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snugug%2Fstarchart-studio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snugug%2Fstarchart-studio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snugug%2Fstarchart-studio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Snugug","download_url":"https://codeload.github.com/Snugug/starchart-studio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snugug%2Fstarchart-studio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33914546,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-10-07T02:03:03.721Z","updated_at":"2026-06-04T16:31:40.642Z","avatar_url":"https://github.com/Snugug.png","language":"Astro","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Starchart Studio\n\nStarchart Studio is a tool to create component stories, similar to [Storybook](https://storybook.js.org/), but designed with [JavaScript islands](https://jasonformat.com/islands-architecture/) and static site generators in mind and powered by [Astro](https://astro.build/).\n\n**This is a preview release!** It's enough to get going with but the UX and DX still needs some work. If you wanna help, please file an issue and we can chat!\n\nCurrent features:\n\n- MDX powered stories\n- Static props and dynamic events\n- Variants\n- Isolated, resizable component preview area\n- Minimalist styling\n\n## Get started\n\nStart by installing [Astro MDX ](https://docs.astro.build/en/guides/integrations-guide/mdx/), then install this module:\n\n```\nnpm install starchart-studio\n```\n\nNext, determine what folder you want to keep your stories in. Stories are MDX files that export information for Starchart Studio to build your story from as well as your long-form documentation. `src/stories` is a good option, but it can be anywhere. A story looks like this (using Astro's starter Card component):\n\n```mdx\nimport Card from '../components/Card.astro';\n\nexport const story = {\n  title: 'Card',\n  component: Card,\n  variants: [\n    {\n      props: [\n        {\n          name: 'title',\n          type: 'text',\n          default: 'Card Title',\n          description: 'The title of the card',\n        },\n        {\n          name: 'body',\n          type: 'text',\n          default: 'Card Body',\n          description: 'The body of the card',\n        },\n        {\n          name: 'href',\n          type: 'url',\n          default: 'https://example.com',\n        },\n      ],\n    }\n  ]\n\n};\n\nThis is Astro's default card component! It's a list item that links to a URL and has a title and body text.\n```\n\nYour story needs to export a `story` object with the following properties:\n\n- `title` - The title of your story\n- `component` - The imported component for your story.\n- `variants` - The different variants for this components, an array of objects containing the following:\n  - `title` (optional) - The title of a variant\n  - `props` (optional) - The properties to pass to your component. Each property needs a `name` (the property name) and a `type` that corresponds to an HTML input type. It can also optionally have a `default` which will be passed in, a `description` of the property, and a `label` to describe the property. Properties get passed in at render time, so cannot be changed once rendered.\n  - `state` (optional) - State that affects your component. State and props share a structure. Hooking up state is a little more complex and is covered below.\n\nNext, create a page (in your Astro `src/pages` directory) to generate the stories in. It can be in whatever folder structure or filename you want, as long as the filename ends in `[story]` for each story to be properly generated (for instance `style-guide/[story].astro`, `stories-[story].astro`). The generated page will replace `[story]` with the filename (minus `.mdx`) of your story. Right now, we recommend a flat folder structure in your stories directory. Once that file is created, add the following to it:\n\n```astro\n---\nimport Starchart from 'starchart-studio/Starchart.astro';\nimport { StarchartStudio } from 'starchart-studio';\n\n/**\n * Builds static paths for stories\n * @return {Promise\u003c{params: Object, props: Object}[]\u003e}\n */\nexport async function getStaticPaths() {\n  // Pass in the glob to your stories\n  return StarchartStudio.getStaticPaths(Astro.glob('../../stories/*.mdx'));\n}\n\n// Chart out your components\nconst starchart = StarchartStudio.chart(Astro);\n---\n\n\u003c!-- Render your Starchart --\u003e\n\u003cStarchart {...starchart} /\u003e\n```\n\nThis will generate unique pages for each story, including stand-alone components for previewing. You can style the page with global CSS, or you can grab the individual sub-components and render them yourself.\n\n## State and Client Loading\n\nIf you need your component to load on the client, or you want to pass state, you're going to need to create a wrapper component as [dynamic elements can't be hydrated](https://docs.astro.build/en/core-concepts/astro-components/#dynamic-tags). Doing so can be as simple as creating an Astro component like so:\n\n```astro\n---\nimport Counter from '../components/Counter.svelte';\n\nexport interface Props {\n  start: number;\n}\n\nconst { start } = Astro.props;\n---\n\n\u003cCounter start={start} client:load /\u003e\n```\n\nHere we've created a file `src/stories/counter.astro` that takes in the same properties as our component (to let us pass properties down), imported our Counter component, and rendered it, passing in the prop and loading it. We then use this component instead of our counter component directly in our story.\n\nIf we want to control our component's state, we start by doing this, then we need to add a little script to let Starchart Studio know how to manage state:\n\n```html\n\u003cscript\u003e\n  import { Starchart } from '@starchart/Starchart';\n\n  // Import your state manager or store here to use with this component\n  import { count } from '../../counterStore';\n\n  // Create a new starchart instance for this component. Use the name of your story here (this would be for counter.mdx)\n  const starchart = new Starchart('counter');\n\n  // This will fire whenever any state update for counter comes in from Starchart, in the form of an object with name: value pairs\n  starchart.onUpdate((data) =\u003e {\n    console.log(data);\n  });\n\n  // This will fire only when an update to the 'count' state comes in from Starchart. You'll get the value\n  starchart.onUpdateTo('count', (data) =\u003e {\n    // Here you update state according to your state manager\n    count.set(Number(data));\n  });\n\n  // You can also go in the other direction. Here we're subscribing to state changes and telling Starchart to update the 'count' state with the provided value, letting state changes work in both directions\n  count.subscribe((value) =\u003e {\n    starchart.send('count', value);\n  });\n\u003c/script\u003e\n```\n\nThis uses Astro's [script bundling](https://docs.astro.build/en/guides/client-side-scripts/#script-bundling) to let you listen for changes sent from Starchart so you can update your component's state, and even lets you update Starchart's state input when state in your component changes! Remember, [sharing state](https://docs.astro.build/en/core-concepts/sharing-state/) in an islands architecture is different than in single-page apps, so you may need to reconsider how you manage state.\n\n## Features\n\n\u003cvideo src=\"https://media.mas.to/masto-public/media_attachments/files/109/600/305/812/185/840/original/c1be52a89c8f86ac.mp4\" role=\"button\" tabindex=\"0\" aria-label=\"Screen recording of Astro-powered story tool in action. Starts with a card component, shows what props are available for the component, a description of the component, and a preview of the component in an iFrame, which is shown being resized on drag. Next switches to a counter component that shows both props and state, which is updated as the component is changed and when the state form item is changed.\" title=\"Screen recording of Astro-powered story tool in action. Starts with a card component, shows what props are available for the component, a description of the component, and a preview of the component in an iFrame, which is shown being resized on drag. Next switches to a counter component that shows both props and state, which is updated as the component is changed and when the state form item is changed.\" loop=\"\" autoplay=\"\" playsinline=\"\" style=\"position: static; top: 0px; left: 0px;\"\u003e\u003c/video\u003e\n\nStarchart will automatically build out the menu of components for you, hook up properties and send and listen for state changes, and render your stories into a nice display. It'll also create an isolated environment for each component preview that's resizable.\n\n## Acknowledgements\n\nIcons are from [Google Material Symbols](https://fonts.google.com/icons?icon.set=Material+Symbols) licensed under the Apache 2.0 license and modified to swap height and width for `viewBox`.\n\nComponent resize area is heavily influenced by [ish.](https://github.com/bradfrost/ish.).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnugug%2Fstarchart-studio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnugug%2Fstarchart-studio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnugug%2Fstarchart-studio/lists"}