@obosbbl/grunnmuren-tailwind

Grunnmuren Tailwind preset. See the Tailwind documentation for more information about how presets work.

Install

# npm
npm install -D @obosbbl/grunnmuren-tailwind@canary tailwindcss postcss autoprefixer

# pnpm
pnpm add -D @obosbbl/grunnmuren-tailwind@canary tailwindcss postcss autoprefixer

Usage

Configure Tailwind to use the preset

/* globals.css */

@import '@obosbbl/grunnmuren-tailwind';

/** Add any auto excluded sources (typically residing in node_modules) */
@source "../../node_modules/@obosbbl/grunnmuren-react/dist";
@source "../../node_modules/@code-obos/obos-layout/dist";

Fonts

Fonts are automatically loaded from OBOS' CDN, so you don't have to host the font files yourself.

If you use Content-Security-Policy, you have to allow https://www.obos.no as a font-src, otherwise the fonts will be blocked from loading.

The preset includes a (local) fallback font to prevent CLS while the fonts are loading. This is similar to the font optimization in Next. This is enabled by default, and can only be disabled by a @theme override of the font variables in your own main tailwind CSS file.

The fallback font metrics is generated with a script that can be run with pnpm font-fallback (requires Bun). If the fonts are changed, the script must be rerun and the resulting file commited.

Migrating from v1?

To ease the transition from v1 to v2 of Grunnmuren, it is possible to configure the preset to be (partially) compatible with v1. This allows you to use v2 of the Tailwind preset with v1 of the React components, and upgrade your application over time instead of a full migration.

To do that you need to configure the preset with legacyV1Compatibility option.

Options

// tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  presets: [require('@obosbbl/grunnmuren-tailwind')({ includeFontFallback: false })],
  // content: [ ... ]
};

The preset supports the following options:

| Name | Default value | Description | | --------------------- | ------------- | --------------------------------------------------- | | includeFontFallback | true | Whether the preset includes a font fallback | | legacyV1Compatibility | false | Configures partial compatibility with Grunnmuren v1 |

Migrating from v2?

Tailwind is upgraded to v4. The grunnmuren-tailwind package is now CSS-first configured. And the previously exposed JS config file is now replaced by a CSS config file.

The legacyV1Compatibility option is removed, so your project has to be fully upgraded to Grunnmuren v2.

The includeFontFallback option is also removed, and a font fallback will automatically be applied to the OBOS fonts by defaullt.

Migration

1. Upgrade your project to Tailwind 4. You can try the migration guide from tailwind.
2. Add @import "@obosbbl/grunnmuren-tailwind"; to the top of the main CSS file of your project. This is the new CSS configuration file for Grunnmuren.
3. If you have a JS/TS tailwind.config in your project and would like to keep it. You can include it in the main CSS file (mentioned in step 2), by using the @config directive, e.g: @config '../tailwind.config.ts';. Read more here.
4. Finally, if you would like to get rid of the old tailwind.config. You can move all your configuration to the main CSS file of your project. Tailwind 4 has automatic content detection, but if you need to include some excluded source you can use the @source directive, e.g: @source "./node_modules/@obosbbl/grunnmuren-react/dist";. You can also extend the @obosbbl/grunnmuren-tailwind config by using various directives such as @base or @theme.

Here is an example of what your main CSS file might look like after migration:

@import "@obosbbl/grunnmuren-tailwind";

@source "../../node_modules/@obosbbl/grunnmuren-react/dist";
@source "../../node_modules/@code-obos/obos-layout/dist"

@theme {
  --animate-custom: custom-animation 1s ease-in-out infinite;
  @keyframes custom-animation {
    0%,
    100% {
      transform: rotate(-3deg);
    }
    50% {
      transform: rotate(3deg);
    }
  }
}

@utility my-custom-util {
  @apply flex flex-col min-h-screen;
}