Add ability to remove dependency on node_modules at runtime

[ZephireNZ]

Add option to not use node_modules layer at launch, for apps which bundle all dependencies into their output.

Describe the Enhancement

Currently, the buildpack node-start will always add a dependency on launch for node_modules. This means that these must be present in the image even though they are unusued.

Possible Solution

Introduce a new environment variable eg BP_NPM_LAUNCH_REQUIRES_MODULES which would be true by default (the current behaviour) but could be set to false to not add a launch requirement on node_modules layer.

This specific line of code would only be run if BP_NPM_LAUNCH_REQUIRES_MODULES is not false:
https://github.com/paketo-buildpacks/node-start/blob/main/detect.go#L39

This would then prevent this section of code being run in npm-install buildpack:
https://github.com/paketo-buildpacks/npm-install/blob/main/build.go#L236-L366

Motivation

For some apps, there is no dependency on the node_modules folder after the app is built. An example of this is nuxt, which ensures all dependencies including node modules are in the output folder.

Removing this layer from the output image should significantly reducing the image size. As an example the node_modules of a project I am working on is just short of 493MB in size, whereas the bundled app is 20MB.

It also removes an unexpected behaviour when using paketo-buildpacks/source-removal as removing node_modules/ folder causes it to throw error:

2025/08/11 00:58:05 readlink /workspace/node_modules: no such file or directory
ERROR: failed to launch: exec.d: failed to execute exec.d file at path '/layers/paketo-buildpacks_npm-install/launch-modules/exec.d/0-setup-symlinks': exit status 1

An example of the /workspace after building nuxt looks like:

• package.json
• node_modules/**/*
• nuxt.config.ts
• src/
  • ...
• .output/
  • public/
  • server/
    • index.mjs <-- Entrypoint
    • package.json <-- Generated by nuxt
    • node_modules/**/*
    • chunks/**/*

[ZephireNZ]

Happy to whip up a PR for this, just wanted to get feedback before I go ahead with trying to change it 😅

[pacostas]

Do you have a sample app with nuxtjs to take a look at it why the paketo-buildpacks/source-removal fails to remove the node_modules?

[till]

@ZephireNZ can you describe how you created your project and add more info?

[ZephireNZ]

Ah sorry, completely forgot to respond to last message 😅

I'll get a minimal example sorted this weekend

[ZephireNZ]

OK so here is an example using the the nuxt starter project.

Run npm create nuxt@latest, prompts are mostly irrelevant but I did:

• Name: demo-nuxt
• Package manager: npm
• Share Usage: no
• Initialise git: no
• Add official modules: no

Run npm install nuxt@3 (version I am using, default Nuxt 4 seems to have an unrelated error when built with buildpack)

Run below pack command:

> pack build demo-nuxt \
  --builder paketobuildpacks/builder-jammy-base:latest \
  --buildpack paketo-buildpacks/nodejs \
  --buildpack paketo-buildpacks/source-removal \
  -e BP_NODE_RUN_SCRIPTS=build \
  -e BP_VERIFY_LAUNCHPOINT=false \
  -e "BP_LAUNCHPOINT=.output/server/index.mjs" \
  -e "BP_INCLUDE_FILES=.output/**/*"

Upon running the container, you will get:

> docker run demo-nuxt:latest
2025/08/30 01:18:47 readlink /workspace/node_modules: no such file or directory
ERROR: failed to launch: exec.d: failed to execute exec.d file at path '/layers/paketo-buildpacks_npm-install/launch-modules/exec.d/0-setup-symlinks': exit status 1

You can confirm that presence of the project-level node_modules folder is not required by running the below directly:

> npm run build
> rm -rf node_modules
> node .output/server/index.mjs
Listening on http://[::]:3000

Now run the same buildpack but with:
-e "BP_INCLUDE_FILES=node_modules/**/*:package-lock.json:package.json:.output/**/*"

This time, the container is able to start up with no issues:

> docker run demo-nuxt:latest
Listening on http://[::]:3000

[till]

Can you set the BP_LAUNCHPOINT to include node?

[till]

I am not a 100% sure about your builder and I am not on my computer to look at the order group, but I think if node-start is included you can also add a start script and the buildpack will select it for the launcher.

We have this for nuxt in the docs:

npm pkg set scripts.start="node ./.output/server/index.mjs"

[ZephireNZ]

Can you set the BP_LAUNCHPOINT to include node?

Same error when I set -e "BP_LAUNCHPOINT=node .output/server/index.mjs"

you can also add a start script and the buildpack will select it for the launcher.

Yep so if I remove BP_LAUNCHPOINT entirely and rely on that instead, it also doesn't work - because npm-start still has the same behaviour where it adds a startup script to fix up the node_modules folder on startup.

> pack-cli build demo-nuxt \
    --builder paketobuildpacks/builder-jammy-base:latest \
    --buildpack paketo-buildpacks/nodejs \
    --buildpack paketo-buildpacks/source-removal \
    -e BP_NODE_RUN_SCRIPTS=build \
    -e "BP_INCLUDE_FILES=output/**/*"
[...]
[detector] err:  paketo-buildpacks/node-start@2.4.1 (1)
[detector] 6 of 11 buildpacks participating
[detector] paketo-buildpacks/ca-certificates 3.10.4
[detector] paketo-buildpacks/node-engine     7.4.1
[detector] paketo-buildpacks/npm-install     2.1.0
[detector] paketo-buildpacks/node-run-script 2.2.1
[detector] paketo-buildpacks/npm-start       2.2.1
[detector] paketo-buildpacks/source-removal  0.2.58
[...]

> docker run demo-nuxt:latest                                                                                                                                                               2025/08/30 08:23:20 readlink /workspace/node_modules: no such file or directory
ERROR: failed to launch: exec.d: failed to execute exec.d file at path '/layers/paketo-buildpacks_npm-install/launch-modules/exec.d/0-setup-symlinks': exit status 1

[ZephireNZ]

To be clear, npm-install is technically the root cause of the error - it is what actually adds the setup-symlinks script causing the issue.

However that buildpack only adds that script when any of the other buildpacks add a launch requirement on node_modules layer (which what node-start and npm-start both always do)

[till]

I'll give it a try later.

On a side note, I also wasn't able to launch nuxt4. Wonder what that is about.

[ZephireNZ]

Decided to write up a PR for this one anyway, and provided a minimal integration test using Nitro (the bundler used by Nuxt)

#755