The CodePen Compiler has access to npm packages during the build process. These packages are listed in the package.json file of a Pen where their versions can be managed.

{
  "dependencies": {
    "lodash": "^4.18.1",
    "lodash-es": "^4.18.1",
    "zod": "^4.6.7",
    "geojson": "^0.5.0"
  },
  "devDependencies": {
    "@types/geojson": "7946.0",
    "@types/lodash": "4.17.27",
    "@types/lodash-es": "4.17.12",
    "zod": "4.6.7"
  }
}
Code language: JSON / JSON with Comments (json)

The packages listed in dependencies are client-side dependencies that are made available via a <script type="importmap"> to your site. The packages listed in devDependencies are made available to Blocks during the build process.

Here are some examples of things you can do:

  • Use third-party TypeScript types, like @types/three
  • Use Babel plugins
  • Use packages in your Vite config (vite.config.js) or Eleventy config (eleventy.config.mjs) for extra functionality
  • Use PostCSS plugins
  • Use ESLint plugins

Build-time packages are never sent to the browser and never appear in your page’s import map. They exist only for the build.

Adding Packages

Add the package to devDependencies in /package.json. If your Pen has no package.json yet, you can manually create one.

{
  "devDependencies": {
    "gray-matter": "^4.0.3"
  }
}Code language: JSON / JSON with Comments (json)

That’s it. There is no terminal and no install command. On the next build, CodePen installs the packages you declared and makes them available to the Blocks that run. The first build after you change the list takes a little longer while the install happens; builds after that reuse it.

Versions work the way they do in npm: an exact version like 4.0.3, or a range like ^4.0.3. Only packages from the npm registry are supported. Git URLs, tarball URLs, and local paths are not.

CodePen Adds Missing Packages Automatically

You often don’t have to edit package.json by hand. If a config file imports a package that isn’t declared yet, the build notices it is missing, adds it to devDependencies with the most recent version, and rebuilds. You’ll see a toast message about a build-time package detected. The new package will appear in your package.json.

The same thing happens for TypeScript types. When you import a package that doesn’t ship its own type definitions, CodePen looks up the matching @types package (and other potential places for third-party types) and adds it, so type checking works without you hunting for it.

CodePen never changes a devDependencies entry you already have. Once a version is recorded, it’s yours to edit.

Using One Package in Both Places

Some packages run in both worlds. A Markdown parser package might render content at build time in an Eleventy data file and again in the browser for a live preview. Declare it under both dependencies and devDependencies.

CodePen keeps the two aligned as far as it can. When it records a build-time package you’ve already declared under dependencies, it uses the same release, so the Node copy and the browser copy match. If the two end up on different major versions, the build shows a warning naming both so you can fix it.

Safety

Installing arbitrary npm packages on a shared service deserves some care, so every build-time package, including everything it depends on, is screened before it is used:

  • Versions with a known vulnerability or malware advisory are refused.
  • Brand-new packages, published to npm less than seven days ago, are refused until they are a week old. New versions of established packages are fine.
  • Install scripts (like postinstall) never run.

A refused package stops the build with an error that names the package, the version and why. Declared versions are never silently swapped for different ones. If the screening service can’t be reached, the build reports that, and you can retry it.

Which Blocks Use Build Packages

Not every single Block needs build-time packages. It’s only relevant for Blocks that support arbitrary plugins or have config that is executable JavaScript. Any of the Vite-based Blocks (like Vue, Svelte, or React) use build-time packages. Babel, ESLint, and PostCSS support plugins (just mention them by name in their configs) thus use build-time packages. But blocks like Sass or Lightning CSS have no use for them.

Was this article helpful?
YesNo
Last updated: November 20, 2026