Ambient Declarations Work, But `Declare Global` is Lost in a Monorepo Workspace Using pnpm: A Comprehensive Guide

If you’re a developer working with a monorepo workspace using pnpm, you might have stumbled upon an issue where `declare global` is lost, leaving you wondering what’s going on. Fear not, dear reader, for we’ve got you covered! In this article, we’ll dive into the world of ambient declarations, `declare global`, and how to make them work seamlessly in your monorepo workspace using pnpm.

What are Ambient Declarations?

Ambient declarations, a feature introduced in TypeScript 3.7, allow you to declare types that aren’t actually present in your code. Think of them as a way to tell TypeScript, “Hey, I know this type isn’t explicitly defined, but I promise it’s there!” This feature is particularly useful when working with external libraries or modules that don’t provide their own type declarations.

// ambient.d.ts
declare module 'external-library' {
  export function doSomething(): void;
}

In the example above, we’re creating an ambient declaration for the `external-library` module, specifying that it exports a `doSomething` function. This declaration allows us to use the `external-library` module in our code, even though it doesn’t provide its own type declarations.

The `Declare Global` Conundrum

Now, let’s talk about the `declare global` syntax. When you use `declare global`, you’re telling TypeScript to merge the declared types into the global namespace. This can be useful when you want to augment existing types or create new ones that are globally accessible.

// globals.d.ts
declare global {
  interface Window {
    myCustomProperty: string;
  }
}

In this example, we’re using `declare global` to add a new property called `myCustomProperty` to the `Window` interface. This property is now globally accessible and can be used throughout your application.

The Issue with pnpm and Monorepo Workspaces

Here’s where things get interesting. When using pnpm in a monorepo workspace, you might notice that your `declare global` declarations are being lost. This is because pnpm creates a separate `node_modules` directory for each package in your monorepo, which can lead to issues with ambient declarations and `declare global` statements.

When you run `pnpm install` or `pnpm build`, pnpm creates a new `node_modules` directory for each package. This means that the `globals.d.ts` file containing your `declare global` statements is not being included in the compilation process.

Solving the Problem: A Step-by-Step Guide

Don’t worry, we’ve got a solution for you! To make `declare global` work in a monorepo workspace using pnpm, follow these steps:

1. Create a new file called `globals.d.ts` in the root of your monorepo workspace. This file will contain your `declare global` statements.

2. In each package’s `tsconfig.json` file, add the following configuration:

   {
     "compilerOptions": {
       // ... other options ...
       "typeRoots": ["../node_modules/@types", "./globals.d.ts"]
     }
   }
       

   This tells TypeScript to include the `globals.d.ts` file in the compilation process for each package.

3. In your `pnpm.config.js` file, add the following configuration:

   module.exports = {
     // ... other configurations ...
     hooks: {
       readPackage: (pkg) => {
         pkg.types = './globals.d.ts';
         return pkg;
       }
     }
   }
       

   This tells pnpm to include the `globals.d.ts` file in the `node_modules` directory for each package.

4. Run `pnpm install` or `pnpm build` to re-create the `node_modules` directories and include the `globals.d.ts` file.

5. Verify that your `declare global` statements are now being recognized by TypeScript.

Additional Tips and Tricks

Here are a few extra tips to keep in mind when working with ambient declarations and `declare global` statements in a monorepo workspace using pnpm:

• Make sure to keep your `globals.d.ts` file organized and maintainable. You can use folders and subfolders to categorize your declarations.

• If you’re using a linter, make sure to configure it to ignore the `globals.d.ts` file. You don’t want to get pesky linting errors!

• When using `declare global`, be mindful of naming collisions. Make sure to choose unique names for your declared types to avoid conflicts.

• If you’re working with a large monorepo, consider using a tool like `tsd` or `type-coverage` to help manage your type declarations.

Conclusion

In conclusion, ambient declarations and `declare global` statements can be a powerful tool in your TypeScript arsenal. By following the steps outlined in this article, you can make them work seamlessly in your monorepo workspace using pnpm. Remember to keep your `globals.d.ts` file organized, and don’t hesitate to reach out if you have any further questions or issues.

Keyword	Description
Ambient declarations	Declaring types that aren’t explicitly defined in your code
`Declare global`	Merging declared types into the global namespace
pnpm	A package manager for JavaScript
Monorepo workspace	A single repository containing multiple packages

Happy coding, and may the type safety be with you!

Frequently Asked Question

Stuck in a monorepo workspace using pnpm? Don’t worry, we’ve got you covered! Here are some answers to your burning questions about ambient declarations and `declare global`.