{"id":22423318,"url":"https://github.com/prantlf/requirejs-esm-preprocessor","last_synced_at":"2026-03-10T04:33:49.587Z","repository":{"id":57307179,"uuid":"477503602","full_name":"prantlf/requirejs-esm-preprocessor","owner":"prantlf","description":"Preprocessor of JavaScript modules in RequireJS projects converting ESM to AMD.","archived":false,"fork":false,"pushed_at":"2025-11-09T17:09:25.000Z","size":240,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-09T17:18:05.349Z","etag":null,"topics":["amd","es6","esm","preprocessor","requirejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prantlf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-04-04T00:41:01.000Z","updated_at":"2025-11-09T17:09:28.000Z","dependencies_parsed_at":"2024-08-06T09:09:15.082Z","dependency_job_id":null,"html_url":"https://github.com/prantlf/requirejs-esm-preprocessor","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/prantlf/requirejs-esm-preprocessor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Frequirejs-esm-preprocessor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Frequirejs-esm-preprocessor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Frequirejs-esm-preprocessor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Frequirejs-esm-preprocessor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prantlf","download_url":"https://codeload.github.com/prantlf/requirejs-esm-preprocessor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Frequirejs-esm-preprocessor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30324444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T01:36:58.598Z","status":"online","status_checked_at":"2026-03-10T02:00:06.579Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amd","es6","esm","preprocessor","requirejs"],"created_at":"2024-12-05T18:09:59.068Z","updated_at":"2026-03-10T04:33:49.576Z","avatar_url":"https://github.com/prantlf.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESM to AMD Preprocessor for RequireJS\n\nA preprocessor of JavaScript modules in [RequireJS] projects converting ESM to AMD. It takes care only of the module format; it does not transpile the language and that is why it is [a lot faster] than plugins using [Babel]. If you need to transpile the code to an earlier ECMAScript version, have a look at [requirejs-babel7].\n\nA file preprocessor is a lot less intrusive than a RequireJS plugin. However, it requires a pluggable development web server, so that a plugin (compatible with [connect middleware]) can be registered in it. The production web server has not limitations, because the bundled output of [RequireJS optimizer] contains AMD modules. (Preprocessing takes place in the `onBuildRead` callback.) Have look at [requirejs-esm] if you are looking for a RequireJS plugin without these limitations.\n\nThe official [RequireJS optimizer] (`r.js`) does not wire up source maps from the original (not transpiled) sources to the source map of the output bundle. It makes this or similar preprocessors unfeasible for serious work. If you want the proper support for source maps, replace the official optimizer package ([`requirejs`]) with the forked [`@prantlf/requirejs`], which is fixed.\n\n## Installation\n\nThis module can be installed in your project using [NPM], [PNPM] or [Yarn]. Make sure, that you use [Node.js] version 14 or newer.\n\n```sh\nnpm i -D requirejs-esm-preprocessor\npnpm i -D requirejs-esm-preprocessor\nyarn add requirejs-esm-preprocessor\n```\n\n## Usage\n\nAdd the following property to the build configuration file for the RequireJS optimizer:\n\n```js\n{\n  onBuildRead: (moduleName, path, contents) =\u003e {\n    const { preprocess } = nodeRequire('requirejs-esm-preprocessor')\n    return preprocess({ path: moduleName, contents })\n  }\n}\n```\n\nCreate a file `server.js` to be used as the development web server:\n\n```js\nconst { serve } = require('requirejs-esm-preprocessor')\nserve({\n  // Transform local sources; not require.js loaded on the page from node_modules\n  isScript: path =\u003e path.endsWith('.js') \u0026\u0026 path.startsWith('/src/')\n})\n```\n\nIf your project contains source scripts ending with `.js`, which should be transpiled, and all other scripts loaded on pages by `script` elements end with `.min.js`, you can use the ready-to-use command line server:\n\n    requirejs-esm-serve\n\nYou can use the ESM module format in modules loaded as dependencies by RequireJS. The main application script cannot be an ESM module, because it would be wrapped in a `define` statement. The main application script i ssupposed to include a `require` statement to perform the application initialisation.\n\nThis plugin transpiles only ESM source files. If it detects a statement calling functions `define`, `require` or `require.config` on the root level of the source file, it will return the text of the source file as-is.\n\nSee also a [demo-local] project, which includes sources only from the local `src` directory:\n\n```sh\nnpm run start:local\nopen http://localhost:8967/demo-local/normal.html\nopen http://localhost:8967/demo-local/optimized.html\n```\n\n## Advanced\n\nYou can bundle ESM modules from outside of your source root too. For example:\n\n```js\nimport { html, render } from 'lit-html/lit-html'\nrender(html`\u003cp\u003eHello, world!\u003cp\u003e`, document.body)\n```\n\nLet `lit-html` be a path alias in the RequireJS configuration pointing to a directory among NPM dependencies outside the source root:\n\n```js\npaths: {\n  'lit-html': '../node_modules/lit-html'\n},\n```\n\nHowever, the relative paths of model dependencies outside the source root will be based on the source root, instead on the module path outside of the source root. One way how to deal with this problem is resolving the relative module paths manually by trimming the directories from absolute module paths:\n\n```js\n{\n  onBuildRead: (moduleName, path, contents) =\u003e {\n    const { preprocess } = nodeRequire('requirejs-esm-preprocessor')\n    const cwd = process.cwd()\n    // Base all modules from local sources on the source root\n    const appDir = `${cwd}/src`\n    // Remove the root of external modules; expect the external\n    // module directories in the RequireJS `paths` configuration\n    const dirMap = { [`${cwd}/node_modules/`]: '' }\n    return preprocess({ path, contents, appDir, dirMap })\n  }\n}\n```\n\nIf you want to merge the NPM dependencies bundled in your project with the other outside of your project, you can rebase their root, so that they would appear next to with other external static assets in the browser debugger:\n\n```js\n{\n  onModuleBundleComplete: ({ path }) =\u003e {\n    const { rebaseMapFile } = nodeRequire('requirejs-esm-preprocessor')\n    rebaseMapFile(`${path}.map`, { [`${process.cwd()}/node_modules/`]: '../node_modules/' });\n  }\n}\n```\n\nThe development web server must not transform static assets that are not meant to be bundled in the optimised output:\n\n```js\nconst { serve } = require('requirejs-esm-preprocessor')\nserve({\n  isScript: path =\u003e path.endsWith('.js') \u0026\u0026\n    !path =\u003e path.endsWith('.min.js') \u0026\u0026\n    !path.endsWith('/require.js'),\n  dirMap: { '/node_modules/': '' }\n})\n```\n\nSee also a [demo-extern] project, which includes sources from the local `src` directory and from `node_modules` outside of it:\n\n```sh\nnpm run start:extern\nopen http://localhost:8967/demo-extern/normal.html\nopen http://localhost:8967/demo-extern/optimized.html\n```\n\n## API\n\n```ts\ninterface DirMap {\n  [ key: string ]: string\n}\n\ntype NeedsResolve = (sourcePath: string, currentFile: string) =\u003e boolean\n\ninterface ResolveOptions {\n  dirMap?: DirMap\n  needsResolve?: NeedsResolve\n}\n\ninterface AmdOptions {\n  namespace?: Record\u003cstring, unknown\u003e\n  func: Record\u003cstring, unknown\u003e\n  name: string\n  deps?: string[]\n  params?: string[]\n  factory?: Record\u003cstring, unknown\u003e\n  output?: Record\u003cstring, unknown\u003e\n}\n\ntype OnBeforeTransform = (options: OnBeforeTransformOptions) =\u003e void\ntype OnAfterTransform = (options: OnAfterTransformOptions) =\u003e void\ntype OnBeforeUpdate = (options: AmdOptions) =\u003e boolean\ntype OnAfterUpdate = (options: AmdOptions) =\u003e boolean\n\nresolvePath(sourcePath: string, currentFile: string, options?: ResolveOptions): string\n\nrebasePath(path: string, dirMap?: DirMap): string\nrebaseMap(map: object, dirMap?: DirMap): void\nrebaseMapFile(file: string, dirMap?: DirMap): void\n\ntype ResolvePath = ((sourcePath: string, currentFile: string, options?: ResolveOptions) =\u003e string) | false\ntype IsScript = (path: string) =\u003e boolean\n\npreprocess(options?: {\n  path: string, contents: string, dirMap?: DirMap, appDir?: string,\n  needsResolve?: NeedsResolve, resolvePath?: ResolvePath = false,\n  useStrict?: boolean = true, sourceMap?: boolean = true,\n  onBeforeTransform?: OnBeforeTransform, onAfterTransform?: OnAfterTransform,\n  onBeforeUpdate?: OnBeforeUpdate, onAfterUpdate?: OnAfterUpdate,\n  verbose?: boolean, silent?: boolean }): string\n\ntype Handler = (req: http.OutgoingMessage, res: http.IncomingMessage, next: () =\u003e void) =\u003e void\n\nserveFile(req: http.OutgoingMessage, res: http.IncomingMessage, path: string) :void\nserveScript(req: http.OutgoingMessage, res: http.IncomingMessage, options?: {\n  path: string, fullPath: string, dirMap?: DirMap, appDir?: string,\n  needsResolve?: NeedsResolve, resolvePath?: ResolvePath = false,\n  useStrict?: boolean = true, sourceMap?: boolean = true,\n  onBeforeTransform?: OnBeforeTransform, onAfterTransform?: OnAfterTransform,\n  onBeforeUpdate?: OnBeforeUpdate, onAfterUpdate?: OnAfterUpdate,\n  verbose?: boolean, silent?: boolean }): void\npreprocessor(options?: {\n  root?: string = '.', scriptsOnly?: boolean, fallthrough?: boolean,\n  setHeaders?: (res: http.Response, path: string, stat: fs.Stat) =\u003e void,\n  cache?: boolean, isScript?: IsScript, dirMap?: DirMap, appDir?: string,\n  needsResolve?: NeedsResolve, resolvePath?: ResolvePath = false,\n  useStrict?: boolean = true, sourceMap?: boolean = true,\n  onBeforeTransform?: OnBeforeTransform, onAfterTransform?: OnAfterTransform,\n  onBeforeUpdate?: OnBeforeUpdate, onAfterUpdate?: OnAfterUpdate,\n  verbose?: boolean, silent?: boolean }): Handler\n\ninterface ServerOptions {\n  root?: string = '.'\n  isScript?: IsScript\n  scriptsOnly?: boolean\n  host: string = process.env.HOST || '0.0.0.0'\n  port: number = process.env.PORT || 8967\n  dirMap?: DirMap\n  appDir?: string\n  useStrict?: boolean = true\n  sourceMap?: boolean = true\n  needsResolve?: NeedsResolve\n  resolvePath?: ResolvePath = false\n  onBeforeTransform?: OnBeforeTransform\n  onAfterTransform?: OnAfterTransform\n  onBeforeUpdate?: OnBeforeUpdate\n  onAfterUpdate?: OnAfterUpdate\n  secureOptions?: {\n    port: number = process.env.SECURE_PORT || 9876\n    key?: string | Blob | Buffer = 'dist/certificates/localhost.key'\n    cert?: string | Blob | Buffer = 'dist/certificates/localhost.crt'\n    allowHTTP1?: boolean = true\n  }\n  logOptions?: {\n    format?: string = 'dev'\n    errorsOnly?: boolean = true\n    servedOnly?: boolean = true\n    transforms?: boolean\n    silent?: boolean\n  }\n  leadingHandlers?: Handler[]\n  middleHandlers?: Handler[]\n  trailingHandlers?: Handler[]\n  favicon?: boolean\n  server?: http.Server | false\n  secureServer?: http.Server | false\n  handler?: Handler\n}\n\ninterface OnBeforeTransformOptions extends ServerOptions {\n  program: Record\u003cstring, unknown\u003e\n}\n\ninterface OnAfterTransformOptions extends OnBeforeTransformOptions {\n  callbackBody: Record\u003cstring, unknown\u003e[]\n}\n\ndefaultUsage(): void\ndefaultUnknownArg(arg: string): boolean\nconfigure(options: {\n  args: string[], version: string,\n  usage?: () =\u003e void, unknownArg?: (arg: string) =\u003e boolean\n}): {\n  server?: boolean, secureServer?: boolean, root?: string,\n  host?: string, port?: number, secureOptions?: { port: number },\n  errorsOnly: boolean, servedOnly: boolean,\n  transforms?: boolean, silent?: boolean\n}\n\ncreateHandler(options?: ServerOptions): Handler\ncreateServer(options?: ServerOptions, handler?: Handler): http.Server\ncreateSecureServer(options?: ServerOptions, handler?: Handler): Promise\u003chttp.Server\u003e\nstartServer(options?: ServerOptions,\n  server?: http.Server | false, secureServer?: http.Server | false,\n  handler?: Handler) : Promise\u003c{ server?: http.Server, secureServer?: http.Server }\u003e\nserve(options?: ServerOptions): void\n```\n\n## Contributing\n\nIn lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.\n\n## License\n\nCopyright (c) 2022-2025 Ferdinand Prantl\n\nLicensed under the MIT license.\n\n[Babel]: https://babeljs.io/\n[RequireJS]: http://requirejs.org\n[RequireJS optimizer]: https://requirejs.org/docs/optimization.html\n[requirejs-babel7]: https://www.npmjs.com/package/requirejs-babel7\n[requirejs-esm]: https://www.npmjs.com/package/requirejs-esm\n[`requirejs`]: https://www.npmjs.com/package/requirejs\n[`@prantlf/requirejs`]: https://www.npmjs.com/package/@prantlf/requirejs\n[Node.js]: http://nodejs.org/\n[NPM]: https://www.npmjs.com/\n[PNPM]: https://pnpm.io/\n[Yarn]: https://yarnpkg.com/\n[demo-local]: https://github.com/prantlf/requirejs-esm-preprocessor/tree/master/demo-local\n[demo-extern]: https://github.com/prantlf/requirejs-esm-preprocessor/tree/master/demo-extern\n[default module name resolution]: https://github.com/prantlf/requirejs-esm-preprocessor/blob/master/src/resolve-path.js#L4\n[resolvePath]: https://github.com/tleunen/babel-plugin-module-resolver/blob/master/DOCS.md#resolvepath\n[a lot faster]: https://github.com/prantlf/requirejs-esm/tree/master/perf/README.md#readme\n[connect middleware]: https://github.com/senchalabs/connect/wiki\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Frequirejs-esm-preprocessor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprantlf%2Frequirejs-esm-preprocessor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Frequirejs-esm-preprocessor/lists"}