Code example requires ES module setup to support top-level await

[Ashish-bbg]

Which application is this bug report for?

Documentation

Issue description

The code example in the documentation uses import and top-level await:

import { REST, Routes } from 'discord.js';

await rest.put(...); 

This throws a SyntaxError unless the project is set up as an ES module, either by:

• Adding "type": "module" in package.json, or

• Renaming the file extension to .mjs

Even though the TOP they mentions "Node.js 22.12.0 or newer", that alone isn’t enough — top-level await is only supported in ES modules.

The code example in the documentation (see here) uses import and top-level await:

Suggestion

To run the code exactly as written (using import and top-level await), one of the following changes should be made:

• Update the documentation to mention that the project must use ES Modules by:
  • Adding "type": "module" to package.json, or
  • Renaming the file to .mjs

OR

• Change the code example to use CommonJS (require) and wrap the await in an IIFE:

const { REST, Routes } = require('discord.js');

(async () => {
  await rest.put(...);
})();

Steps to Reproduce

1. Create a new file named deploy-commands.js

2. Copy the example code from the documentation:

   import { REST, Routes } from 'discord.js';
   
   const rest = new REST({ version: '10' }).setToken('your-token');
   
   await rest.put(Routes.applicationCommands('your-client-id'), {
     body: [{ name: 'ping', description: 'Replies with Pong!' }],
   });

3. Run the file using Node.js 22+:

    node deploy-commands.js 

4. Observe the following error:

     SyntaxError: Cannot use import statement outside a module

or

  SyntaxError: await is only valid in async functions and the top level bodies of modules

The code example in the documentation (see here) uses import and top-level await:

Versions

• Node.js: v22.16.0
• discord.js: v14.19.3
• OS: Windows 10

Issue priority

Medium (should be fixed soon)

[almostSouji]

As of version 22.7 node uses syntax detection and the example should run with a warning about re-parsing causing a performance overhead along with instructions on how to remove those ¹. Accordingly, the recommended version 22.12.0 (though, really, people should generally use the recommended LTS) is beyond that point and should work as advertised.

(node:6378) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///Users/user/Documents/test/index.js is not specified and it doesn't parse as CommonJS.
Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
To eliminate this warning, add "type": "module" to /Users/user/Documents/test/package.json.
(Use `node --trace-warnings ...` to show where the warning was created)

Footnotes

1. https://nodejs.org/api/packages.html#syntax-detection ↩

[Ashish-bbg]

@almostSouji 👋Thanks for the quick response!

I did some deeper testing with Node.js v22.16.0 and I wanted to clarify why the example still fails for me (and likely others too):
Although Node 22+ supports auto module detection with a warning, it still throws a fatal SyntaxError when import is used at the top of a .js file without either:

• "type": "module" in package.json, or
• using a .mjs file extension.
  Even after adding a harmless line like console.log() above the import, Node shows the warning:

Warning: Failed to load the ES module...

…but then it still throws:

SyntaxError: Cannot use import statement outside a module

So while reparsing is attempted, top-level import still isn't allowed unless the file is already marked as an ES module via .mjs or type: module.

🔁 Suggestion

To avoid confusion for others (especially beginners), it may help to mention in the docs or example that:

If you're using .js, you must either:

Set "type": "module" in your package.json, or

Rename the file to .mjs

Even though Node will try to reparse, it still requires an explicit module setup when using import.

[Jiralite]

Can you please provide your setup, because I also cannot reproduce this. Can you find a source for your claims too?

[Qjuh]

I think your issue here is that you explicitly have "type": "commonjs" in your package.json.

[Ashish-bbg]

@almostSouji @Jiralite @Qjuh @millette

Yes, you guys are absolutely right — my package.json had "type": "commonjs", and removing it resolved the issue.

But I’d still suggest updating the example with a short note, because:

When someone runs npm init -y, the generated package.json defaults to "type": "commonjs", which causes this example to fail with a SyntaxError.

So for most users, running the example as-is in a new Node project still won't work unless they:

• remove "type": "commonjs", or
• set "type": "module", or
• rename the file to .mjs

Even with Node 22.12.0+, the presence of "type": "commonjs" disables re-parsing and causes the top-level import to throw.

[Ashish-bbg]

I appreciate you updating the documentation to clarify the ESM requirement—it'll help avoid confusion for others too!