While one lets you organize your UI components, the other lets you interact with them. Yes, we’re talking about Single Directory Components (SDC) and Storybook. Integrating them transforms your development process, making it revolutionary in how UI components are built and tested.
Let's dive straight into this intriguing article and discover how leveraging the power of SDC and Storybook can accelerate build time and boost your efficiency.
What is SDC
Did you know that SDC was a contributed module but it is now included in Core from version Drupal 10.3?! SDC, also known as Single Directory Components, represents a new way of structuring and organizing components. What are components? Components in Drupal are reusable building blocks of code that can include Twig templates, metadata, styles, and scripts that needs to be embedded in Drupal templates.
With SDC, developers can easily create components that are swappable and modular, enhancing the overall flexibility and reusability of their codebase.
What is Storybook
Storybook serves as a frontend workshop that helps developers and designers see and test everything in one place before using them in the actual site. What's better, it is opensource, extremely popular and has a user-friendly interface, making it a tool for modern development workflows!
Storybook lets you develop and test components in isolation. This ensures they work independently before integration. It offers a visual catalog of components so it is easy to see and understand each component’s functionality.
Why integrate SDC with Storybook in Drupal
Integrating SDC with Storybook in Drupal brings many benefits.
It keeps components organized and easy to manage JS and css files, templates, and data flow within components.
You can see and test components in isolation, enhancing the overall maintainability and scalability of UI components.
Speeds up development and ensures everything works perfectly.
Improves collaboration between teams.
Helps maintain a consistent design across the site.
How to integrate SDC with Storybook in Drupal
Setting up and configuring Storybook with Drupal is a straightforward process that involves creating SDC, enabling them, and installing the necessary dependencies. By following a series of steps, developers can seamlessly integrate SDC with Storybook, leveraging tools like Twig and Webpack5 to enhance the templating and rendering capabilities of their components.
Step 1: Setting Up SDC
Enable the SDC core module. It comes out of the box from Drupal 10.1 & above.
If you want to learn how to create SDCs, you can follow this in depth article we wrote previously.
Step 2: Configure Storybook
Install composer require 'drupal/storybook:^1.0@beta'
Setting up development.service.yml
parameters:
# ...
twig.config:
debug: true
cache: false
# Disable development mode in production!
storybook.development: true
cors.config:
enabled: true
allowedHeaders: ['*']
allowedMethods: ['*']
allowedOrigins: ['*']
exposedHeaders: false
maxAge: false
supportsCredentials: true
Run the command:drush role:perm:add anonymous 'render storybook stories'
Under the root folder, run the below commands to set up the storybook:yarn set version berry echo 'nodeLinker: node-modules' >> .yarnrc.yml# Install and configure stock Storybook. yarn dlx sb init --builder webpack5 --type serverCheck out the Storybook Drupal module to learn more.
Step 3: Create Stories for Components
Develop stories for each SDC component to showcase its functionality and variations.
Utilize Twig files to define the structure and content of each component story.
Ensure that each story accurately represents the behavior and appearance of the corresponding component.
Try it out with an example
Here’s an example of the file structure to create an SDC component with Storybook integration. The component here is “formatted-text”.
Here, the atomic component-driven approach is chosen. So, under atoms, we have placed the formatted-text component.Note: SDC components must be placed under the components/ folder.
Coding snippets for the above component:
1. formatted-text.component.yml
2. formatted-text.css
We can create an SCSS file and then compile it into a CSS file. Here's how to do that in a gulp.js file:
gulp.src([‘.components/**/*.scss’]).pipe(gulpSass()).pipe(gulp.dest([‘./components’]))
3. formatted-text.stories.twig
Here, we create the stories by adding them using the {% story <name> with { args } %} syntax. The {% stories %} tag serves as the wrapper for all {% story %} tags, as outside of it, the stories have no context.
4. formatted-text.twig
The main template file of the SDC component.
Step 4: Generate Component Stories
The Storybook application doesn’t understand stories in Twig format. The stories must be compiled into *.stories.json files. To do so you can run: drush storybook:generate-all-stories
If you want to generate stories while watching for files. You can run this command:
watch --color drush storybook:generate-all-stories
Step 5: Test and iterate
Run the command to start the storybook server and test components: yarn storybook
Iterate on the design and functionality of components based on feedback and testing results.
Continuously refine and improve the SDC components to enhance their usability and performance.
This is how your storybook page will look like:
Final Thoughts
While integrating SDC with Storybook offers numerous advantages, it's important to consider potential drawbacks. Some systems may experience performance issues, and not all add-ons may work seamlessly with decorators (controllers of different viewport parameters). Complexities may arise when dealing with multi-nested embeds or higher-order components, requiring careful consideration during development.
Despite these challenges, the integration of SDC and Storybook opens up a new level of possibilities for developers. By creating agnostic components that can be used across different platforms, developers can enhance component visibility via Drupal UI and explore future opportunities, such as integrating components via the layout builder API.
PubDate