Skip to navigation Skip to navigation Skip to content

Running commands

Learn about Hydrogen's CLI tool and how to use it to build CSS.

Initializing a project #

You might have been introduced to this command on the installation page, but let's dive into what the initialization script does for you in detail. You'll only ever need to run this script once when you first install Hydrogen on your project.

When run, it will prompt you to enter both an input and output directory. The input directory is where Hydrogen will look for your markup to scan. While you're only prompted for a single directory at first, you can add as many directories to this array as you want after Hydrogen has been initialized. The output directory is where Hydrogen will put its final CSS file, and any variable files you've requested. If you've enabled debugging, this directory will also be where Hydrogen places its log files.

The initialization script then creates a hydrogen.config.json file in the directory you've run the script. This file contains everything you'll need to configure Hydrogen, and includes helpful defaults you can start with.

terminal 
1
npx h2-init

Running a build #

The build script is what you'll use most when developing with Hydrogen. When executed, it runs the following to build your CSS:

  1. Find and validate your configuration file
  2. Parse the input you pass to it for Hydrogen attributes
  3. Assemble custom CSS based on the attributes you've used
  4. Run the resulting CSS through Lightning CSS for automated browser prefixing and file minification
  5. Generate a CSS variable file if you've requested one
  6. Export the final Hydrogen CSS file

The build script will also log any potential errors, typos, or warnings it finds to your console, so keep an eye out for them. If you need more robust debugging, you can enable log files in your configuration file using the debug setting.

terminal 
1
npx h2-build

Compiling on the fly #

The watch command will automatically watch the directories you've defined in your input configuration for changes. When it detects a change, it will rerun Hydrogen's build script for you on the fly, so that changes are automatically compiled as you work.

terminal 
1
npx h2-watch

Flags #

Hydrogen also offers the ability to customize certain build settings through the use of CLI flags. This allows you to run different variations of the build or watch scripts in unique contexts. Flags accept a boolean (true or false) value, and if provided no value, will default to true.

Processing flags #

Processing flags allow you to control how the final CSS output is processed, including options for Lightning CSS.

  • --h2_prefix will enable/disable browser prefixing.
  • --h2_minify will enable/disable file minification.
  • --h2_error_recovery will allow Lightning CSS to run regardless of errors.
  • --h2_write_css_file tells Hydrogen whether you want it to write a final CSS file
terminal 
1
2
3
4
npx h2-build --h2_prefix
npx h2-build --h2_minify
npx h2-build --h2_error_recovery
npx h2-build --h2_write_css_file

Log flags #

Logging flags allow you to control whether debug log files are generated, as well as how verbose Hydrogen's console output is.

  • --h2_logs will enable/disable log file generation for debugging.
  • --h2_verbose will toggle how much contextual information is displayed by Hydrogen in the console.
terminal 
1
2
npx h2-build --h2_logs
npx h2-build --h2_verbose

Environment flags #

Environment flags are handy groups of pre-defined settings that optimize the build for development and production environments.

  • --h2_env_dev groups the following settings:
    • Prefixing: true
    • Minification: false
    • Logs: false
    • Timers: false
    • Verbose: true
  • --h2_env_prod groups the following settings:
    • Prefixing: true
    • Minification: true
    • Logs: false
    • Timers: false
    • Verbose: false
terminal 
1
2
npx h2-build --h2_env_dev
npx h2-build --h2_env_prod