frame.addScriptTag(options) inserts a script into a specific Puppeteer frame and resolves to a handle for the resulting HTMLScriptElement. Its five documented, optional options are content, id, path, type, and url. Use content for JavaScript text, path for a local file, or url for an external script. For a relative path in Node.js, the base is process.cwd().
What Frame.addScriptTag() does
Puppeteer’s Frame.addScriptTag(options) adds a script element to the selected frame. The method returns a Promise<ElementHandle<HTMLScriptElement>>, so you can retain a handle to the inserted element. See the Frame.addScriptTag() API reference.
A Puppeteer Frame represents a DOM frame, such as an iframe. Use the frame method when the script belongs in a particular frame. By contrast, page.addScriptTag(options) is a shortcut for page.mainFrame().addScriptTag(options) and targets the main frame. JavaScript run in a frame does not affect nested frames inside it. See the Frame reference and Page.addScriptTag() API reference.
The five documented options
| Option | Purpose | Use it when |
|---|---|---|
content |
JavaScript source to inject into the frame. | Your script is already available as a string. |
id |
Sets the script element’s id attribute. |
You need to identify the inserted element. It does not provide the script source. |
path |
Loads a JavaScript file from a path. | The script is stored locally. In Node.js, a relative path resolves from process.cwd(). |
type |
Sets the script element’s type. |
For an ES2015 module, set type: 'module'. |
url |
Loads a script from a URL. | The script source is available at an external URL. |
All five properties are optional. The API reference does not specify defaults or establish how the method behaves if multiple source options—content, path, and url—are combined. Choose one source option rather than relying on undocumented precedence. The option definitions are in the official API reference.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Choose the source and target frame
Inline JavaScript with content
Use content when you have the JavaScript text in your Node.js program:
const scriptHandle = await frame.addScriptTag({
content: 'window.exampleFlag = true;',
id: 'example-script'
});The id is optional and sets the element attribute; it does not change the code being injected.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
A local file with path
Use path to load a JavaScript file from disk:
const scriptHandle = await frame.addScriptTag({
path: './scripts/helper.js',
id: 'helper-script'
});In Node.js, ./scripts/helper.js is resolved from the process working directory, available as process.cwd(). That may differ from the directory containing the source file that calls Puppeteer. If a relative path cannot be found, check the working directory and consider passing an absolute path.
An external script with url
Use url to identify a remote JavaScript file:
const scriptHandle = await frame.addScriptTag({
url: 'https://example.com/library.js'
});This option identifies the external script source. The API reference does not describe detailed behavior for unreachable URLs, so handle errors in your own automation rather than assuming a particular failure mode.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Rank #3
ES2015 modules with type
Set type: 'module' to indicate an ES2015 module:
const scriptHandle = await frame.addScriptTag({
path: './scripts/module.js',
type: 'module'
});The documented module indication is module; the reference does not define additional module-specific behavior for this method.
Targeting a particular frame
Call addScriptTag() on the Frame you want to modify. If the target is the page’s main frame, the equivalent shortcut is page.addScriptTag(options). Do not assume adding a script to one frame also adds it to nested frames.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Basic error handling and troubleshooting
The API references establish the options and return value, but do not specify detailed errors for invalid paths, unreachable URLs, or combined source options. The checks below are practical diagnostics, not claims about a guaranteed Puppeteer error message.
- A relative file path is not found: verify the Node.js process working directory with
process.cwd(). Resolve the file path from that directory or pass an absolute path. - The script appears in the wrong document: verify which frame receives the call.
page.addScriptTag()targets the main frame; call the method on the intendedFramefor another frame. - The script element is present but the expected code is not working: confirm that the correct source option and frame were chosen. For an ES2015 module, use
type: 'module'. - More than one source option is set: do not depend on undocumented precedence. Use one of
content,path, orurl. - The operation rejects: catch the promise rejection in your automation and inspect the path, URL, and target frame. The cited API documentation does not establish the cause or exact error text for each failure.
Or skip the browser setup
If your goal is a page image or PDF rather than injecting JavaScript into a Puppeteer frame, ScreenshotNeo provides a one-request screenshot API. This is not a replacement for frame scripting; it is an alternative for capturing a page without setting up a browser workflow. See the ScreenshotNeo documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp- Cookie banners, popups, and chat widgets are removed before the shot.
- Bot checks, blank pages, and failed loads are never billed.
- An MCP server lets AI agents use screenshot tools.
- The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
What does Frame.addScriptTag() return?
A promise that resolves to an ElementHandle for the inserted HTMLScriptElement.
Does Page.addScriptTag() target an iframe?
The Page method is documented as a shortcut for page.mainFrame().addScriptTag(options), so use a Frame method call for a particular frame.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
