Installation

Guide to installing the core Wander Design System packages

Prerequisites

  • Node.js 22+
  • TypeScript 5.8+
  • Package manager (npm, pnpm, yarn, or bun)

Platform-specific requirements

  • Web: Next.js 15+ (recommended) or any React 18+ framework

Installing packages with GitHub Packages

To use the design system packages, create a GitHub Personal Access Token with read:packages scope, configure npm to use GitHub Packages, and export the your token as the GITHUB_TOKEN environment variable in your terminal:

echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc
echo "@wandercom:registry=https://npm.pkg.github.com" >> .npmrc
export GITHUB_TOKEN=[YOUR_GITHUB_TOKEN]

Learn more about authenticating with a GitHub Personal Access Token.

Installing web components

pnpm add @wandercom/design-system-tokens @wandercom/design-system-fonts @wandercom/design-system-shared
pnpm add @wandercom/design-system-web

Components install to components/ui/ and blocks install to components/blocks/ in your codebase with the required dependencies.

Adopting individual packages

Fonts

Install the fonts package:

pnpm add @wandercom/design-system-fonts

The design system uses Instrument Sans, a clean geometric sans-serif typeface for Wander's brand.

If using Next.js 15+, import and configure the font in your root layout:

import { instrumentSans } from '@wandercom/design-system-fonts/next';

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={instrumentSans.variable}>
      <body>{children}</body>
    </html>
  );
}

For other frameworks, use the font files directly by importing from @wandercom/design-system-fonts/instrument-sans/*.

Tokens (Web)

After installing the tokens package, import the tokens CSS file in your application root or globals.css along with @tailwindcss and our design tokens and components:

import '@tailwindcss';
import '@wandercom/design-system-tokens/tailwind.css';
import '@wandercom/design-system-web/components';

Configure Tailwind to use the imported tokens. Tokens are available as standard Tailwind classes.

TypeScript configuration

Ensure your tsconfig.json includes proper module resolution:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "resolvePackageJsonExports": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Troubleshooting

Common issues:

  • Component not found: Ensure you ran the add command for the component
  • Styles not loading: Verify design tokens are imported in your application root
  • TypeScript errors: Verify TypeScript 5.8+ and proper module resolution in tsconfig.json

Platform-specific:

  • Web: Ensure Tailwind v4 is configured correctly

Next steps