Fixing Jlpm Build Errors With Jest Types In JupyterLite

Dec 21, 2025 by Alex Johnson 56 views

Hey there, fellow developers and JupyterLite enthusiasts! Have you ever found yourself scratching your head, staring at a baffling build error while trying to get your JupyterLite extension off the ground? Specifically, one that pops up when you've included "types": ["jest"] in your tsconfig.json? You're not alone! This is a surprisingly common jlpm build challenge, especially when working with templates that enable testing right out of the box. It leads to a cryptic TypeScript error like 'FS' only refers to a type, but is being used as a value here originating from @jupyterlite/services. Don't sweat it; we're going to dive deep into why this happens and, more importantly, how to fix it so you can get back to building amazing things with JupyterLite. Our goal here is to unravel this mystery, provide clear solutions, and equip you with the knowledge to avoid such headaches in your future projects. By the end of this article, you'll understand the intricacies of TypeScript type resolution, compiler options, and how to effectively manage your development environment for seamless JupyterLite extension creation.

Understanding the `jlpm` Build Challenge in JupyterLite

When you're embarking on the exciting journey of extending JupyterLite with a new kernel, like following the official tutorial and using a project template, you expect a smooth ride, right? These templates, designed for convenience, often come pre-configured with testing setups, including a tsconfig.json file that specifies "types": ["jest"]. This little line is usually a blessing for developers, automatically pulling in all the necessary type definitions for Jest, making your test code a joy to write with autocompletion and type checking. However, in the specific context of JupyterLite, especially when you start integrating core components like @jupyterlite/services, this helpful configuration can unexpectedly turn into a roadblock, throwing a jlpm build error. The error message you might encounter, node_modules/@jupyterlite/services/lib/contents/emscripten.d.ts:6:28 - error TS2693: 'FS' only refers to a type, but is being used as a value here., is a clear indicator of a type declaration conflict. This isn't just a random hiccup; it points to a deeper interaction between how Jest declares its types globally and how other libraries, particularly those leveraging powerful tools like Emscripten within @jupyterlite/services, define their own essential types. jlpm, being the package manager and build orchestrator for JupyterLab and JupyterLite extensions, is simply reporting what TypeScript, our vigilant type checker, is telling it. The core of the problem lies in the fact that @jupyterlite/services includes type definitions for Emscripten, which exposes a global FS object (representing the Emscripten file system). When "types": ["jest"] is active, Jest might introduce its own global FS type (or related identifiers) into the TypeScript compilation context, causing an ambiguity or direct conflict with Emscripten's FS type. TypeScript then gets confused: Is FS a type, a value, or both in different contexts? This leads to the TS2693 error because at line 6 of emscripten.d.ts, typeof FS expects FS to be a value and a type, but due to the Jest type pollution, TypeScript only sees it as a type, hence the conflict. It's a classic case of type declaration merging gone awry, where one set of global types inadvertently clashes with another critical set, leading to a build failure. Understanding this initial interaction is key to appreciating why the simple act of disabling "types": ["jest"] temporarily resolves the issue, but also why a more robust solution is needed for a sustainable development workflow.

Diving Deeper into TypeScript `types` and `tsconfig.json`

To truly grasp why "types": ["jest"] can cause such a fuss in a JupyterLite build, we need to zoom in on TypeScript's core configuration file: tsconfig.json. This isn't just any JSON file; it's the brain of your TypeScript project, dictating how your code is compiled, what rules apply, and where TypeScript should look for crucial information. Among its many powerful options, the types compiler option is particularly relevant here. When you specify "types": ["jest"], you're telling the TypeScript compiler, "Hey, please include all the ambient type definitions for the 'jest' package, and make them available globally throughout my project." This is incredibly convenient for testing, as it means you don't have to explicitly import every Jest-related type or function in every test file. TypeScript automatically makes types like expect, describe, it, and various utility types available. However, this global inclusion mechanism, while handy, can sometimes lead to unexpected conflicts, especially in complex projects that integrate multiple libraries with their own global declarations. The issue we're facing stems from this very mechanism. Different libraries, especially those that bridge JavaScript with lower-level code (like Emscripten does for C++), often define their own global interfaces or objects. Emscripten, which is used within @jupyterlite/services to provide capabilities like a virtual file system, has its own definition for an FS object, which represents the file system itself. This FS object is fundamental to how Emscripten-based services operate. Now, when Jest's global types are pulled in via "types": ["jest"], it's possible that Jest, perhaps through some of its internal testing utilities or mock environments, also introduces a global identifier named FS or something similarly conflicting. TypeScript, during its type resolution phase, tries to reconcile these multiple declarations of FS. The error TS2693: 'FS' only refers to a type, but is being used as a value here. explicitly tells us that in the context where EmscriptenFS = typeof FS; is being defined, TypeScript expects FS to be a symbol that can be used in a typeof expression (meaning it should have a runtime value and a type). However, due to the conflicting global declarations, perhaps Jest's FS definition (if it exists) has shadowed or merged in a way that makes TypeScript only see FS as a type definition, not a symbol with a runtime value. This misunderstanding prevents TypeScript from correctly inferring the type of the Emscripten FS object, leading to the build failure. Other common types arrays might include things like "node" (for Node.js globals), "webpack", or "mocha", all of which bring their own set of global declarations. Understanding this delicate balance and the potential for global type pollution is crucial for debugging complex TypeScript errors and maintaining a healthy project configuration. This deep dive into tsconfig.json and the types option illuminates why seemingly benign configurations can have ripple effects throughout your entire build process, especially when working with interconnected library ecosystems like JupyterLite and its underlying services.

The Root Cause: Type Declaration Collisions with EmscriptenFS and Jest

The heart of our jlpm build problem lies in a specific type declaration collision, clearly pointed out by the TypeScript compiler: node_modules/@jupyterlite/services/lib/contents/emscripten.d.ts:6:28 - error TS2693: 'FS' only refers to a type, but is being used as a value here.. Let's break down what's happening here. The file emscripten.d.ts is a TypeScript declaration file, providing type information for the Emscripten runtime within @jupyterlite/services. Emscripten is a powerful toolchain that compiles C/C++ code into WebAssembly, enabling high-performance, low-level operations in the browser—something critical for certain JupyterLite functionalities. A key component of Emscripten is its virtual file system, which is typically exposed through a global object named FS. In TypeScript, FS would be declared both as a runtime value (the actual file system object) and as a type (describing its structure and methods). The line type EmscriptenFS = typeof FS; in the emscripten.d.ts file is trying to define a new type, EmscriptenFS, by taking the type of the value FS. This is a perfectly valid and common TypeScript pattern when you want to create a type alias based on an existing variable's type. However, when we introduce "types": ["jest"] into our tsconfig.json, things get messy. Jest, being a comprehensive testing framework, operates in a global context and often introduces its own set of global types and declarations to facilitate testing. While Jest itself might not directly define a global FS variable in the same way Emscripten does, the broad nature of its type declarations can sometimes include or implicitly conflict with common global identifiers. For instance, Jest might define an FS type (e.g., related to mock file systems or test runners that deal with file paths) without a corresponding runtime value in the global scope that TypeScript expects when typeof FS is used in the Emscripten context. The crucial distinction here is between a type and a value in TypeScript. A type describes the shape of data, while a value is the actual data itself at runtime. When TS2693 occurs, it means TypeScript, in that specific context (line 6 of emscripten.d.ts), is interpreting FS only as a type, not as a symbol that could also represent a runtime value. This happens because Jest's global type declarations might have overridden, merged incorrectly, or shadowed Emscripten's intended declaration of FS, leading TypeScript to believe that FS is only a type, and thus, typeof FS becomes an invalid operation in that particular context. Essentially, Jest's type declarations are globally polluting the TypeScript environment in a way that clashes with how @jupyterlite/services expects its Emscripten types to be resolved. The simplest way to confirm this is by disabling "types": ["jest"]. When you do, the Jest-related global type declarations are no longer included, the conflict disappears, and TypeScript can correctly interpret Emscripten's FS as both a type and a value, allowing the build to succeed. This isn't a flaw in Jest or JupyterLite per se, but rather a tricky interaction of global type declarations that requires careful management in a complex TypeScript project.

Practical Solutions: Navigating Type Conflicts in Your JupyterLite Project

Now that we understand the core problem, let's explore some practical and robust solutions to fix this jlpm build error without compromising your ability to write tests or build your JupyterLite extension. The key is to manage your TypeScript configuration strategically, especially when dealing with global type declarations.

Solution 1: Temporarily Disabling `types: ["jest"]` (The Immediate Fix)

As you've already discovered, the quickest way to get your jlpm build to pass is to simply remove or comment out "types": ["jest"] from your tsconfig.json. This immediately resolves the conflict because the problematic global Jest type declarations are no longer included in the compilation context for your main project files. Why this works: By removing this line, TypeScript no longer sees the conflicting global FS type (or related identifiers) that Jest might introduce, allowing emscripten.d.ts to be processed without error. Implications: While this gets your build working, it might affect your testing environment. If you rely on global Jest types for autocompletion and type checking in your test files, you might find that expect, describe, and other Jest globals are no longer recognized. You might need to explicitly import these from @jest/globals in your test files (import { jest, describe, it, expect } from '@jest/globals';) or rely on your test runner (like jest itself) to implicitly inject these globals at runtime. This approach is a good starting point for debugging but isn't ideal for a long-term, well-typed development workflow.

Solution 2: Isolating Test Configuration with Separate `tsconfig.json` Files

This is arguably the cleanest and most recommended approach for managing type conflicts between your main application code and your test code. The idea is to have a base tsconfig.json for your primary project compilation and a separate tsconfig.test.json (or similar) specifically for your test files. How to implement it:

Create a tsconfig.json for your main project: This file will contain all the compiler options necessary for building your JupyterLite extension, without the "types": ["jest"] option. It focuses solely on ensuring your extension code compiles correctly.

// tsconfig.json (for your main build)
{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "lib": ["es2020", "dom"],
    "declaration": true,
    "outDir": "lib",
    "rootDir": "src",
    "strict": true,
    // ... other options
  },
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"]
}

Create a tsconfig.test.json for your test files: This file will extend your base tsconfig.json and then add the "types": ["jest"] option, along with any other test-specific configurations. This way, Jest's global types are only active when you're compiling or type-checking your test files.

// tsconfig.test.json
{
  "extends": "./tsconfig.json", // Extend your base config
  "compilerOptions": {
    "types": ["jest"], // Add Jest types ONLY for tests
    "composite": true,
    "isolatedModules": true
  },
  "include": ["src/**/*.ts", "src/**/*.spec.ts", "src/**/*.test.ts"],
  "exclude": ["node_modules", "lib"]
}

Configure your build and test scripts:
- For your regular jlpm build command (or tsc), make sure it uses the main tsconfig.json.
- For your test command (jest or tsc --build tsconfig.test.json), ensure it uses tsconfig.test.json.
Typically, Jest will handle its own TypeScript configuration if you use ts-jest, and it will automatically pick up tsconfig.test.json if it's configured correctly, or you can specify it in your jest.config.js.

This separation ensures that your main build process remains clean from potential global type conflicts, while your tests still benefit from full type-checking and autocompletion with Jest's global types. It's a robust solution that maintains strict type safety across different parts of your project.

Solution 3: More Granular Type Control with `typeRoots` (Advanced)

If for some reason, separating tsconfig files isn't feasible, you can try to use typeRoots in tsconfig.json to be more explicit about where TypeScript looks for type definitions. This is a more advanced approach and can be trickier to manage. typeRoots specifies an array of directories where type definition packages are located. By default, TypeScript looks in node_modules/@types. You could, in theory, create a custom @types directory that doesn't include Jest's type definitions for your build process, and then point typeRoots to it. However, this often leads to more complexity and potential issues with other type definitions. A simpler use of typeRoots might be to exclude the node_modules/@types/jest directory from your main build if your build tool supports it, but this is less common and often less effective than the tsconfig separation. For most JupyterLite extension developers, the separate tsconfig approach (Solution 2) offers the best balance of simplicity and effectiveness.

Choosing the right solution depends on your project's complexity and your team's preferences, but the goal remains the same: to have a robust jlpm build that works consistently, alongside a fully type-checked testing environment. By implementing one of these strategies, you can resolve the TS2693 error and maintain a smooth development workflow for your JupyterLite extensions.

Best Practices for JupyterLite Extension Development

Developing JupyterLite extensions, while incredibly rewarding, often involves navigating a landscape of intricate tools and configurations. To prevent future headaches and ensure a smooth development experience, adopting a few best practices can make a world of difference. These practices extend beyond just fixing build errors and contribute to a more maintainable, scalable, and collaborative project.

First and foremost, modular tsconfig.json files are your best friends. As discussed in the solutions, having a distinct tsconfig.json for your main build and a separate tsconfig.test.json for your testing environment is paramount. This separation ensures that conflicting global type declarations (like the Jest FS issue we tackled) are contained within their respective scopes. Your base tsconfig.json should focus on the core compilation of your extension, guaranteeing that your production code is built with the strictest type checking relevant to its runtime environment. The test-specific tsconfig.test.json can then extend this base, adding test-specific configurations, including the "types": ["jest"] option, without polluting your main build process. This modularity not only solves immediate conflicts but also makes your project's configuration clearer and easier to debug, as you know exactly which rules apply to which part of your codebase.

Next, favor explicit imports over relying on global types. While "types": [...] options are convenient, over-reliance on globally available types can lead to less readable code and introduce hidden dependencies. Whenever possible, use explicit import { something } from 'module'; statements. This makes your code's dependencies clear at a glance and reduces the chance of global type pollution or naming conflicts. For instance, instead of assuming jest globals are always available, explicitly importing import { describe, it, expect } from '@jest/globals'; in your test files makes their origin unambiguous and your code more portable across different environments or future configurations.

Regular version management is another critical practice. Keep your dependencies, especially core ones like @jupyterlite/services, @jupyterlab/services, and typescript itself, updated. Type declaration issues, like the one we've discussed, can often be resolved in newer versions of libraries as maintainers improve their type definitions or address compatibility quirks. Regularly checking for updates and integrating them into your project can save you from encountering already-fixed bugs and ensures you're leveraging the latest improvements in type safety and performance. However, always exercise caution and review changelogs when updating, as breaking changes can sometimes occur.

Engaging with the community is an invaluable resource. If you encounter a perplexing issue that seems unique to your setup, chances are someone else has faced something similar. Don't hesitate to check the JupyterLite, JupyterLab, and TypeScript GitHub issues, forums, or community chat channels. Posting well-documented questions or searching for existing discussions can provide quick solutions, workarounds, or even highlight areas where the tools themselves could be improved. The open-source community is a rich source of knowledge and collaborative problem-solving.

Finally, cultivate a deeper understanding of your tools, particularly TypeScript's type resolution mechanisms. Knowing how TypeScript searches for types, resolves modules, and handles declaration merging empowers you to diagnose and solve complex type errors more efficiently. Familiarize yourself with options like moduleResolution, baseUrl, paths, and typeRoots in your tsconfig.json. This knowledge will not only help you fix immediate problems but also enable you to architect more robust and scalable JupyterLite extensions in the long run. By embracing these best practices, you'll transform potential roadblocks into stepping stones, building a smoother and more enjoyable development journey for your JupyterLite projects.

Conclusion: Building Robust JupyterLite Extensions

We've navigated the sometimes-tricky waters of jlpm build errors in JupyterLite, specifically zeroing in on the 'FS' only refers to a type, but is being used as a value here error that pops up when "types": ["jest"] clashes with Emscripten type declarations in @jupyterlite/services. It's a prime example of how seemingly small configuration details in tsconfig.json can have significant ripple effects throughout a complex TypeScript project. The core takeaway here is that while Jest's global types are incredibly useful for testing, they need to be managed carefully to avoid conflicts with other libraries that also introduce their own global type definitions, especially in a rich ecosystem like JupyterLite.

Our journey together has shown that the most effective and sustainable solution isn't to abandon testing or to completely strip down your tsconfig.json. Instead, it lies in smart configuration management: creating separate tsconfig.json files for your main application build and your test environment. This modular approach ensures that each part of your project compiles with the appropriate type definitions, preventing undesirable conflicts and maintaining a clear separation of concerns. By adopting this strategy, your jlpm builds will run smoothly, and your tests will remain fully type-checked, giving you the best of both worlds.

Remember, building robust JupyterLite extensions means not just writing great code, but also understanding and mastering your development environment. By applying these insights and best practices – from modular tsconfig files to explicit imports and regular dependency updates – you'll be well-equipped to tackle future challenges and contribute amazing tools to the Jupyter ecosystem. Keep exploring, keep building, and don't let a cryptic error message stand in your way!

For more information and to deepen your understanding, check out these trusted resources:

Understanding the jlpm Build Challenge in JupyterLite

Diving Deeper into TypeScript types and tsconfig.json