{ "doc": { "id": "api/node-events/preprocessors-api", "title": "Preprocessors API in Node Events", "description": "Prepare support and spec files for the browser with preprocessors.", "section": "api", "source_path": "/llm/markdown/api/node-events/preprocessors-api.md", "version": "1375fa62d5875962138c8c43f27d7e1235a504a5", "updated_at": "2026-04-29T19:28:48.012Z", "headings": [ { "id": "api/node-events/preprocessors-api#preprocessors-api", "text": "Preprocessors API", "level": 1 }, { "id": "api/node-events/preprocessors-api#examples", "text": "Examples", "level": 2 }, { "id": "api/node-events/preprocessors-api#defaults", "text": "Defaults", "level": 2 }, { "id": "api/node-events/preprocessors-api#usage", "text": "Usage", "level": 2 }, { "id": "api/node-events/preprocessors-api#the-callback-function-should-return-one-of-the-following", "text": "The callback function should return one of the following:", "level": 3 }, { "id": "api/node-events/preprocessors-api#file-object", "text": "File object", "level": 2 }, { "id": "api/node-events/preprocessors-api#file-events", "text": "File events", "level": 2 }, { "id": "api/node-events/preprocessors-api#receiving-close-event", "text": "Receiving 'close' event", "level": 3 }, { "id": "api/node-events/preprocessors-api#sending-rerun-event", "text": "Sending 'rerun' event", "level": 3 }, { "id": "api/node-events/preprocessors-api#source-maps", "text": "Source maps", "level": 2 }, { "id": "api/node-events/preprocessors-api#publishing", "text": "Publishing", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Preprocessors API" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A preprocessor is the plugin responsible for preparing a\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Support-file", "children": [ { "type": "text", "value": "support file" } ] }, { "type": "text", "value": "\nor a " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Spec-files", "children": [ { "type": "text", "value": "spec file" } ] }, { "type": "text", "value": "\nfor the browser." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A preprocessor could transpile your file from another language (CoffeeScript or\nClojureScript) or from a newer version of JavaScript (ES2017)." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A preprocessor also typically watches the source files for changes, processes\nthem again, and then notifies Cypress to re-run the tests." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Examples" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "We've created three preprocessors as examples for you to look at. These are\nfully functioning preprocessors." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The code contains comments that explain how it utilizes the preprocessor API." } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress/tree/develop/npm/webpack-preprocessor", "children": [ { "type": "text", "value": "webpack preprocessor" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress-browserify-preprocessor", "children": [ { "type": "text", "value": "Browserify preprocessor" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress-watch-preprocessor", "children": [ { "type": "text", "value": "Watch preprocessor" } ] } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Defaults" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "By default, Cypress comes packaged with the webpack preprocessor already\ninstalled." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The webpack preprocessor handles:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "ES2015 and JSX via Babel" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "TypeScript" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "CoffeeScript `1.x.x`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Watching and caching files" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Are you looking to change the default options for webpack?" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If you already use webpack in your project, you can pass in your webpack config\nas\n" }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress/tree/develop/npm/webpack-preprocessor#options", "children": [ { "type": "text", "value": "shown here" } ] }, { "type": "text", "value": "." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If you don't use webpack in your project or would like to keep the majority of\nthe default options, you can\n" }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress/tree/develop/npm/webpack-preprocessor#modifying-default-options", "children": [ { "type": "text", "value": "modify the default options" } ] }, { "type": "text", "value": ".\nEditing the options allows you to do things like:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Add your own Babel plugins" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Modify options for TypeScript compilation" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Add support for CoffeeScript `2.x.x`" } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Usage" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "⚠️ This code is part of the\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/plugins/plugins-guide.md#Using-a-plugin", "children": [ { "type": "text", "value": "setupNodeEvents" } ] }, { "type": "text", "value": " function and\nthus executes in the Node environment. You cannot call `Cypress` or `cy`\ncommands in this function, but you do have the direct access to the file system\nand the rest of the operating system." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "To use a preprocessor, you should bind to the `file:preprocessor` event in your\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/plugins/plugins-guide.md#Using-a-plugin", "children": [ { "type": "text", "value": "setupNodeEvents" } ] }, { "type": "text", "value": " function:" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "on('file:preprocessor', (file) => {\n // ...\n})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "The callback function should return one of the following:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "A promise* that eventually resolves the path to the built file**." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "A promise* that eventually rejects with an error that occurred during\nprocessing." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "* The promise should resolve only after the file has completed writing to disk.\nThe promise resolving is a signal that the file is ready to be served to the\nbrowser." } ] }, { "type": "thematicBreak" }, { "type": "paragraph", "children": [ { "type": "text", "value": "** The built file is the file that is created by the preprocessor that will\neventually be served to the browser." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If, for example, the source file is `spec.coffee`, the preprocessor should:" } ] }, { "type": "list", "ordered": true, "start": 1, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Compile the CoffeeScript into JavaScript `spec.js`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Write that JavaScript file to disk (example: `/Users/foo/tmp/spec.js`)" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Resolve with the absolute path to that file: `/Users/foo/tmp/spec.js`" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "This callback function can and will be called multiple times with the same\n`filePath`." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The callback function is called any time a file is requested by the browser.\nThis happens on each run of the tests." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Make sure not to start a new watcher each time it is called. Instead, cache the\nwatcher and, on subsequent calls, return a promise that resolves when the latest\nversion of the file has been processed." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "File object" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `file` object passed to the callback function has the following properties:" } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Property" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Description" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`filePath`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "The full path to the source file." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`outputPath`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "The suggested path for saving the preprocessed file to disk. This is unique to the source file. A preprocessor can choose to write the file elsewhere, but Cypress automatically provides you this value as a convenient default." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`shouldWatch`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A boolean indicating whether the preprocessor should watch for file changes or not." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "File events" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `file` object passed to the callback function is an\n" }, { "type": "link", "title": null, "url": "https://nodejs.org/api/events.html#events_class_eventemitter", "children": [ { "type": "text", "value": "Event Emitter" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Receiving 'close' event" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When the running spec, the project, or the browser is closed while running\ntests, the `close` event will be emitted. The preprocessor should do any\nnecessary cleanup in this function, like closing the watcher when watching." } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "// example\nconst watcher = fs.watch(filePath /* ... */)\n\nfile.on('close', () => {\n watcher.close()\n})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Sending 'rerun' event" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If watching for file changes, emit `rerun` after a file has finished being\nprocessed to let Cypress know to rerun the tests." } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "// example\nfs.watch(filePath, () => {\n file.emit('rerun')\n})" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Source maps" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress utilizes source maps to enhance the error experience. Stack traces are\ntranslated so that your source files are shown instead of the generated file\nthat is loaded by the browser. This also enables displaying code frames. Without\ninline source maps, you will not see code frames." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "By default, Cypress will include an inline source map in your spec file, so you\nwill get the most out of the error experience. If you\n" }, { "type": "link", "title": null, "url": "/llm/markdown/api/node-events/preprocessors-api.md#Usage", "children": [ { "type": "text", "value": "modify the preprocessor" } ] }, { "type": "text", "value": ", ensure that inline\nsource maps are enabled to get the same experience. Some examples of this include:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "With webpack and the\n" }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress/tree/develop/npm/webpack-preprocessor", "children": [ { "type": "text", "value": "webpack preprocessor" } ] }, { "type": "text", "value": ", set\n" }, { "type": "link", "title": null, "url": "https://webpack.js.org/configuration/devtool/", "children": [ { "type": "text", "value": "the `devtool` option" } ] }, { "type": "text", "value": " to\n`inline-source-map`." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "With esbuild and the\n" }, { "type": "link", "title": null, "url": "https://github.com/bahmutov/cypress-esbuild-preprocessor/tree/main", "children": [ { "type": "text", "value": "esbuild preprocessor" } ] }, { "type": "text", "value": ", set\n" }, { "type": "link", "title": null, "url": "https://esbuild.github.io/api/#sourcemap", "children": [ { "type": "text", "value": "the `sourcemap` option" } ] }, { "type": "text", "value": " to `inline` when\n" }, { "type": "link", "title": null, "url": "https://github.com/bahmutov/cypress-esbuild-preprocessor#esbuild-options", "children": [ { "type": "text", "value": "creating the bundler" } ] }, { "type": "text", "value": "." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "With cucumber and the\n" }, { "type": "link", "title": null, "url": "https://github.com/badeball/cypress-cucumber-preprocessor/tree/master", "children": [ { "type": "text", "value": "cucumber preprocessor" } ] }, { "type": "text", "value": "\nthird party bundlers are used to bundle the code." } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "For esbuild and the\n" }, { "type": "link", "title": null, "url": "https://github.com/bahmutov/cypress-esbuild-preprocessor/tree/main", "children": [ { "type": "text", "value": "esbuild preprocessor" } ] }, { "type": "text", "value": ",\nset " }, { "type": "link", "title": null, "url": "https://esbuild.github.io/api/#sourcemap", "children": [ { "type": "text", "value": "the `sourcemap` option" } ] }, { "type": "text", "value": " to `inline` when\n" }, { "type": "link", "title": null, "url": "https://github.com/bahmutov/cypress-esbuild-preprocessor#esbuild-options", "children": [ { "type": "text", "value": "creating the bundler" } ] }, { "type": "text", "value": ".\nNote: the cucumber preprocessor documentation for the esbuild bundler describes an experimental\noption: `prettySourceMaps`, but this option is buggy and setting source maps on the esbuild\nbundler directly works better." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The other bundlers all default their source maps appropriately." } ] } ] } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If using " }, { "type": "link", "title": null, "url": "https://www.typescriptlang.org/", "children": [ { "type": "text", "value": "TypeScript" } ] }, { "type": "text", "value": " with any custom preprocessor, you will want to make sure that the " }, { "type": "link", "title": null, "url": "https://www.typescriptlang.org/", "children": [ { "type": "text", "value": "TypeScript" } ] }, { "type": "text", "value": "\ncompiler is generating source maps. This can be done by setting the " }, { "type": "link", "title": null, "url": "https://www.typescriptlang.org/tsconfig/#sourceMap", "children": [ { "type": "text", "value": "`sourceMap`" } ] }, { "type": "text", "value": " option in your\n`tsconfig.json` to `true`. The " }, { "type": "link", "title": null, "url": "https://www.typescriptlang.org/tsconfig/#inlineSourceMap", "children": [ { "type": "text", "value": "`inlineSourceMap`" } ] }, { "type": "text", "value": " option is not recommended as it does not provide an accurate code frame.\nPlease see our recommended " }, { "type": "link", "title": null, "url": "/llm/markdown/app/tooling/typescript-support.md#Configure-tsconfigjson", "children": [ { "type": "text", "value": "tsconfig.json" } ] }, { "type": "text", "value": " as a reference." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Publishing" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Publish preprocessors to " }, { "type": "link", "title": null, "url": "https://www.npmjs.com/", "children": [ { "type": "text", "value": "npm" } ] }, { "type": "text", "value": " with the naming\nconvention `cypress-*-preprocessor` (e.g. cypress-clojurescript-preprocessor)." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Use the following npm keywords:" } ] }, { "type": "code", "lang": "json", "meta": null, "value": "\"keywords\": [\n \"cypress\",\n \"cypress-plugin\",\n \"cypress-preprocessor\"\n]" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Feel free to submit your published plugins to our " }, { "type": "link", "title": null, "url": "/llm/markdown/app/plugins/plugins-list.md", "children": [ { "type": "text", "value": "list of plugins" } ] }, { "type": "text", "value": "." } ] } ] }, "token_estimate": 1304 }