Get started — Astro

Astro renders static HTML by default; React components become client-hydrated Islands via the client:* directives. Five steps from a fresh Astro project to your first interactive Oshon component. Requires Node 18+ and Tailwind v4.

1. Create the Astro project

pnpm create astro@latest my-oshon-app
cd my-oshon-app
pnpm astro add react
pnpm install

Pick the "Just the basics" starter and TypeScript: strict. pnpm astro add react registers the React renderer + writes @astrojs/react into astro.config.mjs.

2. Add Tailwind v4

pnpm add -D tailwindcss @tailwindcss/vite

Wire the Vite plugin into astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  integrations: [react()],
  vite: {
    plugins: [tailwindcss()],
  },
});

3. Install Oshon

pnpm add @oshon-ai/components @oshon-ai/tokens @oshon-ai/primitives

4. Wire the tokens

Create src/styles/tailwind.css with the three imports:

src/styles/tailwind.css

@import 'tailwindcss';
@import '@oshon-ai/tokens/css';
@import '@oshon-ai/tokens/tailwind';

Import it once in your layout (or every page that needs Oshon):

src/layouts/Base.astro

---
import '../styles/tailwind.css';
---

<html lang="en">
  <head>
    <slot name="head" />
  </head>
  <body>
    <slot />
  </body>
</html>

5. Render a component

Oshon components are interactive React components, so they need a client:* directive to hydrate. client:load is the safest default.

src/pages/index.astro

---
import { ButtonHug } from '@oshon-ai/components';
import Base from '../layouts/Base.astro';
---

<Base>
  <main style="padding: 32px">
    <h1>Oshon test</h1>
    <ButtonHug client:load>Click me</ButtonHug>
  </main>
</Base>

Run pnpm dev and open the dev URL. The button renders server-side as static HTML, then hydrates client-side when the page loads.

Issues? See Troubleshooting.