TypeScript Setup

TypeScript requires additional configuration to properly handle CSS imports from Typeweave packages. This guide explains how to set up ambient module declarations.

The Problem

If you're encountering TypeScript errors like:

Cannot find module '@typewe/inter' or its corresponding type declarations.
Cannot find module '@typewe/inter/css/index.css' or its corresponding type declarations.

This is due to TypeScript's noUncheckedSideEffects flag rejecting CSS files as having side effects. The solution is to add ambient module declarations to your project.

The Solution

Create a global TypeScript declaration file in your project. The most common location is src/globals.d.ts or src/types/globals.d.ts:

// src/globals.d.ts
declare module "*.css";
declare module "@typewe/*" {}

This tells TypeScript to allow imports from CSS files and all Typeweave packages without type checking them.

Next.js Projects

For Next.js projects, create the declaration file in your project root or src directory:

// app/globals.d.ts or src/globals.d.ts
declare module "*.css";
declare module "*.scss";
declare module "@typewe/*" {}

Make sure your tsconfig.json includes this file:

{
  "compilerOptions": {
    // ... other options
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts",
    "app/globals.d.ts" // Add this
  ]
}

Vite Projects

For Vite projects (React, Vue, Svelte), create the declaration file in your src directory:

// src/vite-env.d.ts (or add to existing vite-env.d.ts)
/// <reference types="vite/client" />

declare module "*.css";
declare module "@typewe/*" {}

Note: Vite projects typically have a vite-env.d.ts file already. You can add the declarations to this existing file.

Create React App

For Create React App projects, create the declaration file in your src directory:

// src/react-app-env.d.ts (or add to existing react-app-env.d.ts)
/// <reference types="react-scripts" />

declare module "*.css";
declare module "@typewe/*" {}

Verification

After adding the declaration file, restart your TypeScript server (in VS Code: Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"). Then verify the import works:

// This should now work without errors
import '@typewe/inter/css/index.css';

function App() {
  return <h1 style={{ fontFamily: 'Inter, sans-serif' }}>Hello World</h1>;
}

Still seeing errors? Make sure your tsconfig.json includes the declaration file in the "include" array, and restart your editor/TypeScript server.