Getting Started with BoomerCSS

⚠️ Alpha Version Notice:

BoomerCSS is currently in alpha stage and has some important limitations:

  • Not compatible with Turbopack - please use webpack for nextjs or other supported bundlers
  • Macros don't play well with build cache in vercel deployments, you might need to disable it or redeploy manually sometimes
  • Macro functions cannot be used across files - theme, animation, and query values must be defined in the same file as css/styled functions
  • API may change without notice
  • Some features are still experimental

Use with caution in production environments.

Prerequisites

If you're using Parcel as your bundler, macros will work out of the box. For other bundlers, follow the configuration instructions in the unplugin-parcel-macros documentation.

Before installing BoomerCSS, you need to set up the required dependencies:

npm install -D unplugin-parcel-macros @parcel/macros

Installation

1. Copy the boomer.ts file from https://github.com/PookMook/boomer-css/blob/main/src/libs/boomer.ts to your project

2. Create a theme file at @/css/theme.ts with your configuration (you can change the path in the file downloaded at step 1):

import { createConfig, globalCSS, v } from '@/libs/boomer' with { type: 'macro' }

// The export are for TypeScript type inference, we are not going to use them.
export const { queries, themeTypeForV } = createConfig({
  theme: {
    base: {
      colors: {
        primary: '#3b82f6',
        // ... your theme values
      }
    }
  }
})

globalCSS({
  // ... your global styles
})

export function run(){}

Basic Setup

When using BoomerCSS, you must import functions with the macro type declaration. This is crucial as the library will throw an error at runtime without it:

import { css } from '@/src/lib/boomer.ts' with { type: 'macro' }