{"id":16363149,"url":"https://github.com/e0ipso/twig-storybook","last_synced_at":"2025-03-21T00:31:49.735Z","repository":{"id":215042765,"uuid":"737903446","full_name":"e0ipso/twig-storybook","owner":"e0ipso","description":"Extends Twig with new \"stories\" and \"story\" tags for easily writing Storybook stories using Twig templates.","archived":false,"fork":false,"pushed_at":"2024-11-13T16:52:04.000Z","size":313,"stargazers_count":5,"open_issues_count":1,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-17T19:21:23.482Z","etag":null,"topics":["php","storybook","twig","twig-extension"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/e0ipso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2024-01-01T22:54:43.000Z","updated_at":"2025-03-05T14:57:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"12780462-1087-4336-96df-5b83b33ddd24","html_url":"https://github.com/e0ipso/twig-storybook","commit_stats":null,"previous_names":["e0ipso/twig-storybook"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e0ipso%2Ftwig-storybook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e0ipso%2Ftwig-storybook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e0ipso%2Ftwig-storybook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e0ipso%2Ftwig-storybook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/e0ipso","download_url":"https://codeload.github.com/e0ipso/twig-storybook/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244717391,"owners_count":20498283,"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":["php","storybook","twig","twig-extension"],"created_at":"2024-10-11T02:26:39.221Z","updated_at":"2025-03-21T00:31:49.729Z","avatar_url":"https://github.com/e0ipso.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Twig Storybook\n\n![GitHub](https://img.shields.io/github/license/e0ipso/twig-storybook)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/e0ipso/twig-storybook)\n![GitHub issues](https://img.shields.io/github/issues-raw/e0ipso/twig-storybook)\n\nTwig Storybook is a Composer package that enhances the Twig templating language by introducing two new Twig tags: `stories` and `story`. With Twig Storybook, you can easily create and manage Storybook stories directly in your Twig templates, making it a powerful tool for documenting and showcasing your frontend components.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\nYou can install Twig Storybook via Composer:\n\n```bash\ncomposer require e0ipso/twig-storybook\n```\n\n## Usage\n\n### With Drupal\nYou don't need to use this package directly, use the [Storybook](https://www.drupal.org/project/storybook)\ndrupal module instead. This library is compatible with Drupal 10, and later.\n\n### Adding Twig Tags\n\nAfter installing the package, you need to register the Twig tags in your Twig environment. Here's how you can do it:\n\n```php\nuse Twig\\Environment;\nuse Twig\\Loader\\FilesystemLoader;\nuse TwigStorybook\\Twig\\StorybookExtension;\n\n// Initialize the Twig environment\n$loader = new FilesystemLoader('path/to/your/templates');\n$twig = new Environment($loader);\n\n// Register the Storybook extension\n$twig-\u003eaddExtension(new \\TwigStorybook\\Twig\\TwigExtension());\n```\n\n### Creating Stories\n\nOnce the Twig Storybook extension is registered, you can start creating stories within your Twig templates. We recommend\nwriting the stories in a file with name `\u003cfile-name\u003e.stories.twig`.\n\n- Use the `{% stories %}` tag to define a group of stories.\n- Use the `{% story %}` tag to define an individual story.\n\nHere's an example:\n\n```twig\n{% stories my_card with {\n  title: 'Components/Examples/Card',\n  argTypes: {\n    iconType: {\n      options: { Power: 'power', Like: 'like', External: 'external' },\n      control: 'radio'\n    }\n  }\n} %}\n\n  {% story default with {\n    name: '1. Default',\n    args: { header: 'I am a header!', text: 'Learn more', iconType: 'power' }\n  } %}\n    {% embed '@examples/my-card' with { header } %}\n      {% block card_body %}\n        \u003cp\u003eI am the \u003cem\u003ecard\u003c/em\u003e contents.\u003c/p\u003e\n        {% include '@examples/my-button' with { text, iconType } %}\n      {% endblock %}\n    {% endembed %}\n  {% endstory %}\n\n{% endstories %}\n```\n\nThis will render as:\n\n![Storybook Screenshot](./docs/sb-screenshot.png)\n\n### Storybook setup\n\nInstall Storybook as usual:\n\n```console\n# Make use of modern versions of yarn.\nyarn set version berry\n# Avoid pnp.\necho 'nodeLinker: node-modules' \u003e\u003e .yarnrc.yml\n# Install and configure stock Storybook.\nyarn dlx sb init --builder webpack5 --type server\n```\n\nThen update `.storybook/main.js` to scan for stories where your application stores them.\n\n### Compiling Twig stories into JSON\n\nThe Storybook application will does not understand stories in Twig format. It will fail to render them. You need to\ncompile them into a `*.stories.json`. To do so, you can leverage the\n`StoryRenderer::generateStoriesJsonFile($template_path, $url)` method. Where the `$template_path` is the location of the\n`*.stories.twig` template, and the `$url` is the base URL in your application that will render the story.\nStorybook will make a request to `\"$url . '/' . $hash\"`, so make sure your application handles that route (see below).\n\nThe [Drupal module implementation](https://www.drupal.org/project/storybook) includes a console command to find all\n`*.stories.twig` and compile them into `*.stories.json`.\n[See the implementation](https://git.drupalcode.org/project/storybook/-/blob/1.x/src/Drush/Commands/StorybookCommands.php).\n\n### Rendering Stories\n\nTo render the Storybook stories, you can use the `StoryRenderer` service. Every framework handles routes differently,\nbut we recommend using the story renderer inside your controller.\n\n```php\n  public function renderStoryControllerHandler(string $hash, Request $request): array {\n    $data = $this-\u003estoryRenderer-\u003erenderStory($hash, $request);\n    return new Response($data);\n  }\n```\n\nTo use this service, wire the services to the container. The Twig Storybook Drupal module does it like this:\n\n```yaml\nservices:\n  logger.channel.twig_storybook:\n    parent: logger.channel_base\n    arguments: ['twig_storybook']\n\n  TwigStorybook\\Service\\StoryCollector: {}\n  TwigStorybook\\Service\\StoryRenderer:\n    arguments:\n      - '@TwigStorybook\\Service\\StoryCollector'\n      - '@logger.channel.twig_storybook'\n      - '%app.root%'\n    calls:\n      - ['setTwigEnvironment', ['@twig']]\n\n  TwigStorybook\\Twig\\TwigExtension:\n    arguments:\n      - '@TwigStorybook\\Service\\StoryCollector'\n      - '%app.root%'\n    tags:\n      - { name: twig.extension }\n```\n\n## Contributing\n\nWe welcome contributions from the community. If you want to contribute to Twig Storybook, please follow these guidelines:\n\n1. Fork the repository.\n2. Create a new branch for your feature or bug fix.\n3. Make your changes and ensure all tests pass.\n4. Submit a pull request with a clear description of your changes.\n\nMake sure to follow the [code of conduct](CODE_OF_CONDUCT.md) when interacting with this community.\n## License\n\nTwig Storybook is open-source software licensed under the [GPL-2 License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe0ipso%2Ftwig-storybook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fe0ipso%2Ftwig-storybook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe0ipso%2Ftwig-storybook/lists"}