{"id":11914,"library":"rechoir","title":"rechoir: Node Environment File Loader Preparer","description":"rechoir is a utility designed to prepare the Node.js `require` environment for dynamically loading files with various non-native extensions. It operates by registering module loaders into `require.extensions`, leveraging `interpret`-like configuration objects to map file extensions to their respective transpiler or loader modules. Currently stable at version 0.8.0, releases are typically feature-driven and occur on an irregular cadence, often in conjunction with updates within the broader Gulp.js ecosystem where it serves as a dependency for tools like `liftoff`. A key differentiator is its ability to integrate with third-party transpilers (e.g., CoffeeScript, TypeScript, Babel) without bundling them, instead requiring developers to install these transpiler modules as local project dependencies. This design makes rechoir a flexible tool for command-line interfaces and build systems that need to process files written in languages other than standard JavaScript directly via Node's module resolution system.","status":"active","version":"0.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/gulpjs/rechoir","tags":["javascript","require","loader","extension","extensions","prepare"],"install":[{"cmd":"npm install rechoir","lang":"bash","label":"npm"},{"cmd":"yarn add rechoir","lang":"bash","label":"yarn"},{"cmd":"pnpm add rechoir","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the configuration object mapping file extensions to module loaders, which is essential for rechoir's functionality.","package":"interpret","optional":false}],"imports":[{"note":"rechoir is primarily a CommonJS module, intended for use with `require()`.","wrong":"import rechoir from 'rechoir';","symbol":"rechoir","correct":"const rechoir = require('rechoir');"},{"note":"The `prepare` method is exposed directly off the main module export.","wrong":"import { prepare } from 'rechoir';","symbol":"prepare","correct":"const rechoir = require('rechoir');\nrechoir.prepare(config, filepath);"},{"note":"While not part of `rechoir` itself, `interpret.extensions` is the canonical configuration object used as the first argument to `rechoir.prepare`.","symbol":"interpret.extensions","correct":"const config = require('interpret').extensions;"}],"quickstart":{"code":"const fs = require('fs');\nconst path = require('path');\nconst config = require('interpret').extensions;\nconst rechoir = require('rechoir');\n\n// Create dummy files for demonstration\nconst fixtureDir = path.join(__dirname, 'fixtures');\nfs.mkdirSync(fixtureDir, { recursive: true });\nfs.writeFileSync(path.join(fixtureDir, 'test.coffee'), 'console.log(\"Hello from CoffeeScript!\");');\nfs.writeFileSync(path.join(fixtureDir, 'test.toml'), '[section]\\nkey = \"value\"');\nfs.writeFileSync(path.join(fixtureDir, 'test.js'), 'module.exports = { js: true };');\n\n// NOTE: For .coffee and .toml, you would typically need to install\n// `coffee-script` and `toml` packages in your project.\n// For this example to run without errors, ensure they are installed or comment out those lines.\n\ntry {\n  rechoir.prepare(config, path.join(fixtureDir, 'test.coffee'));\n  console.log('CoffeeScript file loaded via prepare, attempting require...');\n  require(path.join(fixtureDir, 'test.coffee')); // This will execute the CoffeeScript\n} catch (e) {\n  console.error(`Error preparing/requiring CoffeeScript: ${e.message}. Did you install 'coffee-script'?`);\n}\n\ntry {\n  rechoir.prepare(config, path.join(fixtureDir, 'test.toml'));\n  console.log('TOML file loaded via prepare, attempting require...');\n  const tomlConfig = require(path.join(fixtureDir, 'test.toml'));\n  console.log('TOML content:', tomlConfig); // This will show the parsed TOML\n} catch (e) {\n  console.error(`Error preparing/requiring TOML: ${e.message}. Did you install 'toml'?`);\n}\n\n// Standard JS files don't need prepare\nconst jsConfig = require(path.join(fixtureDir, 'test.js'));\nconsole.log('JavaScript content:', jsConfig);\n\n// Cleanup (optional)\n// fs.unlinkSync(path.join(fixtureDir, 'test.coffee'));\n// fs.unlinkSync(path.join(fixtureDir, 'test.toml'));\n// fs.unlinkSync(path.join(fixtureDir, 'test.js'));\n// fs.rmdirSync(fixtureDir);","lang":"javascript","description":"Demonstrates how to use rechoir with `interpret.extensions` to dynamically register and load files with custom extensions like `.coffee` and `.toml` into the Node.js runtime, allowing them to be `require()`-d like standard JavaScript modules. It highlights the need for local transpiler installations."},"warnings":[{"fix":"Upgrade Node.js to v10.13.0 or higher, or downgrade rechoir to v0.7.1.","message":"Version 0.8.0 dropped support for Node.js versions older than 10.13.0. Projects using older Node.js runtimes will need to remain on rechoir v0.7.1 or update their Node.js version.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Refer to the `rechoir` README for the correct `prepare(config, filepath, [cwd], [noThrow])` API usage and update your code accordingly.","message":"Version 0.5.0 introduced a complete API rewrite. Code written for rechoir versions prior to 0.5.0 is incompatible and will need to be updated to the new `prepare` API.","severity":"breaking","affected_versions":">=0.5.0 <0.8.0"},{"fix":"Update transpiler configurations to align with Babel, using `.babel.js` if necessary, or ensure compatible Babel setups are in place.","message":"Version 0.4.0 switched internal transpilation logic from `6to5` to `babel`, specifically targeting the `.babel.js` extension. Projects relying on `6to5` might experience issues or require configuration changes.","severity":"breaking","affected_versions":">=0.4.0 <0.5.0"},{"fix":"Migrate usage from `load` to the `prepare` method, which became the primary API for registering module loaders.","message":"The `load` method was removed in version 0.3.0. Attempting to call `rechoir.load()` will result in an error.","severity":"deprecated","affected_versions":">=0.3.0"},{"fix":"Ensure that any required transpiler packages (e.g., `npm install coffee-script`) are installed in your project's `node_modules`.","message":"rechoir does NOT bundle transpilers (e.g., `coffee-script`, `@babel/register`, `ts-node`, `toml`). You must install the necessary transpiler or loader packages locally in your project as dependencies for rechoir to successfully register and use them.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Be mindful of other tools in your environment that might also modify `require.extensions`. Debug conflicts by inspecting `require.extensions` before and after `rechoir.prepare()` calls.","message":"Modifying `require.extensions` (which rechoir does) is a global and synchronous operation. While powerful, it can lead to conflicts if multiple libraries attempt to modify the same extension or if the order of registration matters for specific transpilers.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the missing transpiler package: `npm install coffee-script` (or the equivalent for other languages like `ts-node`, `@babel/register`, `toml`).","cause":"The required transpiler for the file extension (e.g., CoffeeScript) is not installed in the project.","error":"Error: Cannot find module 'coffee-script'"},{"fix":"Ensure you are using `const rechoir = require('rechoir');` for CommonJS. If on an old version, update `rechoir` to >=0.5.0.","cause":"The `rechoir` module was incorrectly imported or required, or an older version was installed that does not expose the `prepare` function (e.g., pre-0.5.0).","error":"TypeError: rechoir.prepare is not a function"},{"fix":"Install the `interpret` package: `npm install interpret`.","cause":"`interpret` is a direct dependency for rechoir's configuration, but it is not installed.","error":"Error: The module 'interpret' was not found"},{"fix":"Ensure `interpret` has a mapping for the desired extension, and that the specified loader module (e.g., `node-sass`) is installed. You might need to extend `interpret.extensions` or use a custom configuration object.","cause":"rechoir was asked to prepare an extension (e.g., `.scss`) for which no corresponding module loader is defined in the `interpret` configuration or installed.","error":"Error: No module loader found for '.scss' files."}],"ecosystem":"npm"}