---
title: Modules
---
import EnvBadges from '@theme/EnvBadges';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Load and resolve custom file types at runtime with a Node.js `require` replacement or
next-generation [hooks](https://nodejs.org/api/module.html#customization-hooks). Currently supports
TypeScript for `.ts` and `.tsx` files.
## Installation
```bash
yarn add @boost/module
```
```bash
pnpm add @boost/module
```
```bash
npm install @boost/module
```
## CommonJS requires
Node.js's native `require()` has historically only supported `.js` and `.json` files (and now `.cjs`
too). But what if we were able to require non-JavaScript files at runtime also? Like TypeScript?
This package does just that through a new function called [`requireModule()`][requiremodule].
This function operates by patching the list of allowed file types/extensions in Node.js's module
resolution. Begin by importing the function and importing
[a supported file type](#supported-file-types)!
```ts
import { requireModule } from '@boost/module';
const result = requireModule('./some/non-js/file');
```
> This function should only be used to import module-like files, like JavaScript and TypeScript. It
> should _not_ be used for other file types, like JSON or YAML.
If you'd prefer to _not_ use `requireModule()` and still use native `require()`, but also support
custom file types, you may do so by calling
[`registerExtensions()`](/api/module/function/registerExtensions) at the top of your script or
application entry point.
### Module interoperability
Unlike `require()` which returns imported values as-is, [`requireModule()`][requiremodule] changes
the shape of the import to align with ECMAScript modules. We do this for interoperability and
consistency sake, so that the developer experience is the same for both systems.
So what does this mean exactly? The biggest change is that CommonJS default exports
(`module.exports`) are now returned under a `default` property, like so.
```js title="example.js"
module.exports = 123;
```
```ts
const value = require('./example'); // 123
const { default: value } = requireModule('./example'); // 123
```
Another change is that CommonJS named exports (`exports.`) are returned as properties in the
imported object, as well as properties in an object on the `default` property. This pattern exists
to match Node.js >= v12.20 functionality.
```js title="example.js"
exports.foo = 'abc';
exports.bar = 123;
```
```ts
const value = require('./example');
value.foo; // abc
value.bar; // 123
const value = requireModule('./example');
value.foo; // abc
value.bar; // 123
value.foo === value.default.foo; // true
```
### Generic types
In TypeScript, the native `require()` is typed to return `any`, which isn't that ideal. However,
[`requireModule()`][requiremodule] can type both the default and named exports of a module via
generics.
The 1st generic slot types the default export (`module.exports` for CJS and `export default` for
ESM) under the returned `default` property.
```ts
const result = requireModule('./example');
result.default; // string
```
While the 2nd generic slot types named exports (`exports.` for CJS and `export ` for
ESM) under their respective property names.
```ts
const result = requireModule('./example');
result.foo; // string
result.bar; // number
result.default; // string
```
For backwards compatibility with CommonJS (can't mix `module.exports` and `exports.`), named
exports are also encapsulated under the `default` property. To type this correctly, pass `void` for
the default generic, which passes the type through accordingly.
```ts
const result = requireModule('./example');
result.foo; // string
result.bar; // number
result.default.foo; // string
result.default.bar; // number
```
## Node.js hooks
Node.js supports an _experimental_ feature called
[hooks](https://nodejs.org/api/module.html#customization-hooks), where non-JavaScript files can be
loaded, parsed, and evaluated at runtime through Node.js's module system when using
`import`/`export`.
To make use of hooks, the following requirements must be met.
- Node.js >= v16.20
- Must use `import()` or `import`/`export` syntax (no `require`)
- Source files must be modules (`.mjs`, `.ts`, etc)
- Imported files must have trailing file extensions
If you meet all of these requirements, then you may run your Node.js script with one of the
following patterns.
```shell
# v20+
node --import @boost/module/register ./path/to/entry-point.mjs
# v18+
node --loader @boost/module/hook-typescript ./path/to/entry-point.mjs
# v16+
node --experimental-loader @boost/module/hook-typescript ./path/to/entry-point.mjs
```
For example, with the above you can now import TypeScript files as if they were standard JavaScript!
```ts
// entry-point.mjs
import defaultValue, { namedValue } from './some/file/written/in.ts';
```
## Supported file types
### TypeScript
[TypeScript](https://www.typescriptlang.org/) files are supported for `.ts`, `.tsx`, `.cts`, and
`.mts` file extensions. The TypeScript source code will be down-leveled according to the currently
running Node.js version and its capabilities.
The TypeScript only hook/loader can be referenced with `@boost/module/hook-typescript`.
[requiremodule]: /api/module/function/requireModule