Skip to navigation Skip to navigation Skip to content

Welcome to Hydrogen! #

npm (tag) Netlify

Thanks for visiting Hydrogen's documentation! This site contains everything you'll need to install Hydrogen on your project, create a theme, run commands, style your interfaces, and troubleshoot common problems.

Have a question but can't find the answer here? Submit a ticket on Github and perhaps the community can provide some insight. We'd also love to receive feedback on how this documentation can be improved.

Recent updates #

Learn more about the latest and greatest releases containing new features, optimized tooling, bugfixes, and a better overall experience.

Featured release #

2.0.0 #

This release reworks almost every single feature and option, enabling more reliable output, faster compile times, and loads of new features and options.

major Released: February 1, 2023 🚨 Breaking

✨ New features (9) #
  • Breaking: Hydrogen 2.0.0 represents a completely new approach to CSS that differs drastically from version 1.0.0.
    • Rather than compiling a Sass library and then selectively generating a CSS file for your project, Hydrogen now actively parses data-h2 attribute values using JavaScript and creates CSS on the fly.
    • This approach is significantly faster and more accurate than the previous approach and opens up a world of new possibilities that you can discover in the 2.0.0 documentation.
  • While version 1.0.0 supported over 25 different style properties, this release shatters that limitation by enabling support for every single CSS property out there.
    • Not only can you use any CSS property at your disposal, 2.0.0 supports the use of configured settings
  • 2.0.0 introduces new functionality that enables support for custom, automatically applied themes.
    • By adding the theme's key value to your site's data-h2 wrapper attribute, you can restyle your project in seconds.
    • This functionality also enables the ability to specify unique styles per-theme, meaning you can alter layouts, media, and more.
  • Alongside themes, 2.0.0 also adds support for configuring values that apply to dark mode automatically.
    • This feature also allows you to control how dark mode is applied; whether through media queries or a manual toggle.
    • Each theme you define has access to its own unique styles for light and dark modes, allowing you to customize them as much as you need.
  • 2.0.0 introduces new query-specific references that allow more granular control over the target of your styles.
    • The :selectors[] allows you to apply styles only if the element contains specific selectors (classes, ids, attributes).
    • The :children[] allows you to apply styles to children nested inside the current element, allowing you to bulk style similar elements.
  • A new vertical rhythm and typography system has been implemented that allows you to granularly control how typography appears on your project on a per-media query basis.
    • These typography settings now also directly impact and inform an automatically generated heading typography scale that accounts for default line height.
    • New whitespace multipliers have been added that allow you to apply multiples of your base line-height as units of space, creating unity and consistency between the interface and the typography.
  • Color configurations have been overhauled and improved through the addition of color modifiers.
    • Out of the box, for each of your color configurations, Hydrogen generates 6 alternate colors: light, lighter, lightest, dark, lighter, darkest.
    • Color opacity modifiers have also been improved and now support dynamic calculation, meaning they are no longer limited to fixed values.
    • Alongside default modifiers, you can now also define custom modifiers for your colors, allowing you to set unique values for specific contexts.
  • 2.0.0 introduces a handful of helpful validation steps to help catch unexpected errors in your code.
    • Hydrogen will now validate your configuration file before each run to ensure there aren't any syntax errors.
    • It will also validate each attribute's parsed CSS to try and catch invalid CSS syntax.
  • Hydrogen's CLI commands now accept a series of optional flags, allowing you to customize the output based on environment and build contexts.
🛠️ Optimizations (5) #
  • Hydrogen's documentation has been completely rebuilt from the ground up using 11ty.
  • CSS construction has been improved to leverage the use of CSS variables throughout, allowing for greater control and manipulation by both the system and the end user.
  • The system's code structure and documentation have been significantly improved and organized for better maintenance, debugging, and community contribution.
  • 2.0.0 updates and enhances Hydrogen's console output. Along with more helpful output, you'll find new formatting, configurable settings, detailed timers, and more.
  • Hydrogen now offers a new debugging tool that generates log files containing parsed data that can offer insight into where the tool might be failing.

Latest stable and beta releases #

2.0.5 #

This release fixes a log bug and updates the error output when Lightning CSS fails for easier debugging.

patch Released: March 14, 2024

🛠️ Optimizations (1) #
  • Enhances the error output when Lightning CSS fails so that it includes the line and column values for the CSS location in hydrogen.raw.css.
🪲 Bugfixes (1) #
  • Fixes a bug that prevented the generate_logs configuration from working, which also caused the compile to fail.
📚 Documentation (1) #
  • Removes outstanding references to Autoprefixer and CSSnano from the file.

2.0.0-beta.40 #

beta Released: January 26, 2023 🚨 Breaking

✨ New features (1) #
  • Breaking: Enhances the functionality from the previous release by enabling the fixed use of any configured color in dark mode when the automatic setting is enabled.
    • This means that if you set black to automatically swap to white but need black explicitly in dark mode, you can simply define :dark(black).