Manual setup

For new projects, use the UluBit Astro Starter to begin with the standard project setup and shared UluBit packages already configured.

For an existing Astro project, install and configure @ulubit/foundations and @ulubit/ui directly.

Install the packages

Install the foundations and UI packages:

pnpm add @ulubit/foundations @ulubit/ui

The foundations package uses Sass. If the project does not already have a Sass implementation installed, add sass-embedded:

pnpm add -D sass-embedded

Astro supports Sass through Vite, so no additional Astro integration is needed.

Load the foundations

Import the foundations once from a global stylesheet. For example src/styles/global.scss:

@use "@ulubit/foundations";

Then make sure that stylesheet is loaded by the project’s shared layout or other global entry point:

---
import "@/styles/global.scss"
---

The foundations provide the shared values used across UluBit styling and UI components. Load them globally rather than importing the main foundations stylesheet separately into individual components.

Project-specific global styles can be added alongside the foundations:

@use "@ulubit/foundations";

@use "./base";
@use "./colors";
@use "./typography";

The exact organization of those project styles is up to the project.

Use foundation utilities

Some foundations are Sass utilities rather than global styles.

Import them only in the files that need them.

For example, to use UluBit breakpoint mixins inside an Astro component:

<style lang="scss">
  @use "@ulubit/foundations/breakpoints" as *;

  .example {
    padding: var(--space-s);

    @include at(lg) {
      padding: var(--space-l);
    }
  }
</style>

Other foundation values exposed as CSS custom properties can be used directly after the global foundations stylesheet has been loaded:

.example {
  padding: var(--space-m);
  color: var(--color-text);
}

See the Foundations documentation for the available tokens, utilities, and their intended use.

Use UI components

Import UluBit UI components from @ulubit/ui when they are needed:

---
import { ButtonLink } from "@ulubit/ui"
---

Then use the component normally:

<ButtonLink href="/contact/">
  Contact us
</ButtonLink>

See the Components documentation for available components, properties, variants, examples, and accessibility guidance.

Verify the setup

Start the existing development environment and confirm that:

• the global foundations stylesheet loads without errors
• foundation tokens are available
• Sass utilities compile where they are used
• imported UluBit UI components render correctly

Then run the project’s normal checks and production build.

At minimum:

pnpm build

The build should complete without errors.

The project is now ready to use the Foundations, Components, and Features documentation as needed.