Frequently Asked Questions

This page addresses common issues and questions that users encounter when working with Typeweave.

TypeScript Errors

Cannot find module '@typewe/[font-name]' or its corresponding type declarations

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. To resolve this, add ambient module declarations to your project:

Create a global TypeScript declaration file (e.g., src/globals.d.ts):

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

See the TypeScript Setup guide for more details.

Performance Issues

Large bundle sizes

If your bundle size is larger than expected:

1. Use variable fonts

When available, variable fonts can significantly reduce bundle size compared to importing multiple static weights:

// ✅ Good: Single variable font (one file)
import "@typewe/inter/css/index.css";

// ❌ Avoid: Multiple static fonts (multiple files)
import "@typewe/lato/css/300.css";
import "@typewe/lato/css/400.css";
import "@typewe/lato/css/700.css";

2. Only import fonts you use

Don't import fonts you're not actually using in your application. Each font adds to your bundle size.

Fonts loading slowly

If fonts are taking a long time to load:

  • Use font preloading for critical fonts
  • Ensure you're using the font-display: swap property (default in Typeweave)
  • Consider self-hosting via NPM instead of using the CDN
  • Use variable fonts to reduce the number of HTTP requests

Variable Fonts

Variable font not working

If variable fonts aren't working as expected:

1. Check browser support

Variable fonts are supported in all modern browsers (Chrome 62+, Firefox 62+, Safari 11+, Edge 79+). Ensure your target browsers support variable fonts.

2. Verify font-family name

Use the exact font family name as shown in the documentation:

body {
  font-family: "Inter", sans-serif; /* ✅ Correct */
  font-family: "Inter Variable", sans-serif; /* ❌ Wrong */
}

3. Use any weight value

Variable fonts support any weight from their min to max range:

.heading {
  font-family: "Inter", sans-serif;
  font-weight: 600; /* Any value from 100-900 */
}

NPM vs CDN

Should I use NPM packages or the CDN?

We recommend NPM packages for most use cases. Here's why:

NPM Packages (Recommended)

  • Better performance (no external DNS lookups)
  • Works offline once bundled
  • Version locked in package.json
  • No rate limits
  • Optimized by your bundler

CDN

  • Quick to set up (just a link tag)
  • Good for prototyping
  • Useful when you can't use a bundler
  • Subject to rate limits
  • Depends on external service availability

See our Installation guide to get started with NPM packages.

Need More Help?

If you're still experiencing issues:

  • Check our documentation for detailed guides
  • Review our framework-specific guides (Next.js, Vite, TypeScript)
  • Ensure you're using the latest version of Typeweave packages
  • Check your bundler configuration (Vite, Webpack, etc.)