DriversRecommendedOutdated drivers can make a good PC feel brokenScan driver issues before chasing fixes manually.Scan NowHalloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsWindows FixRecommendedWindows errors stealing your time? Find the fix fastScan stability, cleanup and performance issues.Fix Now×
Skip to content
World desk13 min

How to Set the Node.js Version for Apps Deployed With Coolify

Set Coolify's Node.js version correctly with Nixpacks, understand major-versus-patch behavior, pin a Nixpkgs archive, and know when a Dockerfile is the better choice.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

For a Coolify application built with Nixpacks, set the Node.js major line in one place: package.json (engines.node), .nvmrc, .node-version, or the NIXPACKS_NODE_VERSION build variable. Save the change and redeploy, because Coolify must rebuild the image. If you need a reproducible minor and patch package, pin the Nixpkgs archive in nixpacks.toml; if you need complete image control, use a Dockerfile with an exact base-image tag or digest.

The important distinction is major-line selection versus exact package reproducibility. A setting such as 22 chooses the Node.js 22 line, but the concrete 22.x package comes from the Nixpkgs archive selected by Nixpacks and can change on a later rebuild.

As an Amazon Associate I earn from qualifying purchases.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

How Coolify selects Node.js with Nixpacks

When an application uses Nixpacks, Coolify generates a build plan from the repository and its build variables. Nixpacks looks for Node.js version information in repository configuration such as engines.node, .nvmrc, and .node-version, or in NIXPACKS_NODE_VERSION. The official explanation is in Coolify’s Nixpacks overview.

These settings are inputs to the image build, not a live switch applied to an already-running container. A restart that reuses the existing image keeps the old Node.js package. Any change made at build time therefore requires a new deployment.

#1 Best Overall
Sale
TOZO A1 Wireless Earbuds Bluetooth 5.3 Light Weight in Ear Headphones | IPX5 Waterproof,2 Mics for AI Calls,Immersive Premium Sound Bass Headset with Charging Case,32 EQ via App Black
  • [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
  • [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
  • [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
  • [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
  • [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.

Check the Base Directory first

Nixpacks can only inspect files in the application’s configured Base Directory. That directory must contain the package.json, .nvmrc, or .node-version file you expect it to read. A monorepo commonly fails here: the version file may be at the repository root while Coolify builds from apps/web, or the manifest may be in a subdirectory while the Base Directory points elsewhere.

Before changing a version value, open the application’s configuration and confirm that the selected Base Directory is the directory containing the Node.js project that Nixpacks should build. Check the same location for nixpacks.toml if you are pinning a package set. A correct file in a directory that is outside the build context cannot affect the generated plan.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Method 1: declare the version in package.json

For most Git-based applications, package.json is the clearest repository-level source of truth. Add an engines object or extend the existing one:

{
  "engines": {
    "node": "22"
  }
}

Commit the change and push it to the branch that Coolify deploys. The declaration travels with the application, so another developer or another build environment sees the same requested major line without copying a dashboard setting.

If the manifest already has an engines object, add the node property without deleting the other engine declarations. Keep the value easy to identify in code review, and make sure the committed file is in the Base Directory selected in Coolify. A local edit that is not committed will not be present in a Git-based build.

What value should you use?

Use the major line your dependencies and application support. A value of 22 requests Node.js 22. Expressions such as 22.x or >=22 also describe a compatible major line rather than one immutable patch package. They do not, by themselves, guarantee one minor or patch release.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Keep the declaration consistent with the version used in local development and continuous integration. Do not maintain a different major value in several files unless you have a deliberate reason and a process that checks them for drift. Conflicting signals make it harder to determine which input produced a particular build.

Method 2: use .nvmrc or .node-version

Create either .nvmrc or .node-version in the configured Base Directory and put the desired Node.js version or major line in the file. Nixpacks reads both file names.

22

The file can be useful when your team already uses a version manager locally and wants the same small, dedicated file in the repository. It also avoids adding deployment-specific metadata to a package manifest. Add the file to version control; an uncommitted local file is invisible to a Git-based deployment.

Rank #2
Sale
Smart Watch for Men Women Compatible with iPhone Samsung Android Phone 1.69 inch Full Touch Screen IP68 Waterproof Bluetooh Fitness Tracker Heart Rate/Sleep Monitor (Black)
  • 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
  • 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
  • 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
  • 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
  • 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.

Use one of the two names as your normal convention rather than maintaining different values in both. If both exist for historical reasons, make their contents agree or remove the stale file. The goal is a single value that can be explained when someone reviews a deployment.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Monorepo placement

Place the version file beside the project files Nixpacks is meant to inspect. If the Base Directory is a service subdirectory, put the file there or change the Base Directory to the repository location that contains it. Having a correct file in a different directory does not help the build.

Method 3: set NIXPACKS_NODE_VERSION in Coolify

A Coolify build variable is convenient when different applications or environments need different Node.js major lines without editing the repository. In the application, go to Configuration → Environment Variables and add:

NIXPACKS_NODE_VERSION=22
  1. Open the application’s Configuration page.
  2. Select Environment Variables.
  3. Add NIXPACKS_NODE_VERSION with the required major line, such as 22.
  4. Set Build time to Available during build.
  5. Save the variable.
  6. Deploy the application again.

The build-time toggle is essential. A variable available only to the running container arrives too late for Nixpacks to choose the package during image creation. Coolify’s versioning guidance explicitly says to keep Build time set to Available during build, then redeploy and inspect the build log; see the Node.js versioning guide.

When a dashboard variable is the better choice

Use this method when the same repository is deployed to environments that intentionally use different major lines, or when operations staff must change the build input without modifying application code. Treat the variable as the authoritative setting for that application and document it so a later repository edit does not create two competing values.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Remember that this setting belongs to the Coolify application configuration, not the repository checkout. A new deployment created for a different Coolify application will not automatically inherit it. Record the value with the environment’s deployment settings so a reviewer can reconstruct how the image was built.

Major versions do not pin patch releases

It is easy to read 22 as “Node.js 22.0.0 forever,” but that is not what Nixpacks does. The major selector identifies a compatible Node.js line. Nixpacks obtains the concrete package from the Nixpkgs archive selected for the build. If that archive changes, a rebuild can resolve a different 22.x release even when your application still says 22.

This behavior is often desirable for receiving updates, but it matters when you require byte-for-byte repeatability, a regulated software bill of materials, or a patch-level compatibility test. Decide whether you need a supported major line or an immutable package set before choosing a configuration method.

For example, changing from 22 to 22.x does not create an exact package lock, and adding >=22 permits a compatible major selection rather than identifying one archive revision. The version declaration answers “which Node.js line?” The archive or image definition answers “which concrete package set?” Keep those two decisions separate when documenting a release.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #3
New Bee Guitar Cable 10ft Electric Instrument Bass AMP Cord
  • [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
  • [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
  • [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
  • [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
  • [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by

Pin the Nixpkgs archive with nixpacks.toml

To keep Nixpacks on one package set, add a nixpacks.toml file at the project location used by the build and pin a complete Nixpkgs commit SHA:

[phases.setup]
nixpkgsArchive = '51ad838b03a05b1de6f9f2a0fffecee64a9788ee'

The SHA above is the format shown in Coolify’s documentation. That example archive contains Node.js 22.13.1 according to the documentation at the time it was written, but archive contents are time-sensitive. Verify the Node.js package in the candidate commit and confirm the resolved version in your own build log rather than assuming the example remains unchanged.

Use a complete commit SHA, not a shortened identifier or a moving branch name. The point of the setting is to identify one Nixpkgs revision that can be reviewed and reused. The selected revision still needs to contain the Node.js major and patch that your application requires, so inspect it before adopting the pin.

What an archive pin changes

An archive is a package-set pin, not a Node-only switch. It affects the other Nix packages and system libraries supplied to the build as well. Test the complete application image, including native dependencies, before using a newly selected archive in production.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

How to update a pin safely

  1. Choose a complete nixpkgs commit SHA that contains the Node.js major and patch you intend to use.
  2. Update nixpacks.toml in a branch or non-production environment.
  3. Build and inspect the Nixpacks plan and build log for the resolved Node.js package.
  4. Run the application’s normal tests, especially tests involving native modules or system libraries.
  5. Promote the tested commit and redeploy production.

If you need to change only the Node.js major line and do not need a fixed package set, a regular version declaration is less maintenance than changing the archive. Revisit the archive deliberately when you need a newer package, since updating it can alter more than Node.js.

Use a Dockerfile for image-level control

Switch to a Dockerfile when the deployment needs an explicitly controlled base image, multiple build stages, operating-system packages, or reproducibility at the image layer. A minimal pattern is:

FROM node:22

The 22 tag expresses the Node.js 22 line, but a mutable tag can point to a newer image later. If your policy requires immutable image identity, select the exact digest for the official Node image you intend to run and use that digest in the FROM instruction. Choose the digest deliberately; do not copy an unrelated digest from an example.

Changing the build strategy to Dockerfile moves responsibility for the image definition from Nixpacks detection to your Dockerfile. You must then maintain the build stages, operating-system packages, dependency installation, and start command needed by the application. The payoff is explicit control over the complete base image rather than only the Nixpacks package selection.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

A Dockerfile is therefore not merely another place to write 22. It defines the base image and the steps that produce the application image. Review those steps when changing versions, and verify the resulting image in the deployment log just as you would verify a Nixpacks package.

Rank #4
BSIMB 15.6" Digital Family Calendar & Chore Chart, No Subscription Fees
  • Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
  • Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
  • All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
  • Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
  • Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.

Which method should you choose?

Method Source-of-truth location Travels with repository Patch reproducibility Per-environment changes Image/build control
package.json Application manifest Yes Major line only unless combined with an archive pin Low; changing it changes the code revision Nixpacks defaults
.nvmrc or .node-version Dedicated version file in Base Directory Yes Major line only unless combined with an archive pin Low to medium Nixpacks defaults
NIXPACKS_NODE_VERSION Coolify application configuration No Major line only unless combined with an archive pin High; each application or environment can differ Nixpacks defaults
nixpacks.toml archive pin Repository build configuration Yes Package-set reproducibility, subject to verifying the selected commit Low; update and redeploy the configuration Controls the Nix package set, not every image detail
Dockerfile Repository image definition Yes Use an exact base-image digest for immutable image identity Change the Dockerfile or build context per environment Highest; explicit stages, packages, and base image

The first three methods are version selectors for Nixpacks. They are straightforward when the requirement is “build with the Node.js 22 line.” The archive pin adds package-set repeatability while retaining Nixpacks. Dockerfile control is broader: it covers the base image, operating-system packages, and build stages, but those responsibilities become yours to maintain.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

A reliable deployment and verification workflow

  1. Identify the build strategy. Confirm that the application is using Nixpacks. If it is already configured for a Dockerfile, set the version in that Dockerfile instead of expecting Nixpacks variables to control it.
  2. Confirm the Base Directory. Verify that it contains the intended package.json, version file, or nixpacks.toml.
  3. Choose one primary Node.js setting. Use the manifest, one version file, or the Coolify variable. Remove accidental duplicates or make their agreement an explicit policy.
  4. Check detected commands. In the application’s General settings, review the detected install, build, and start commands. A correct Node.js version does not repair an incorrect command or an unexpected project directory.
  5. Deploy a new image. A build-time change is effective only when Nixpacks runs again. Do not rely on a restart of the existing container.
  6. Read the build output. Inspect the Nixpacks plan and build log for the resolved Node.js package and version. This confirms what was installed rather than what the configuration was intended to request.
  7. Record the result. For production, keep the commit, the selected version declaration, and, when used, the Nixpkgs SHA or Docker image digest together in the deployment record.

Apply the workflow after every version change, including a change made only in Coolify’s dashboard. A successful save is not evidence that the running image changed; the new deployment and its build output are the evidence.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Troubleshooting a wrong Node.js version

The repository setting is ignored

First check the Base Directory. If it does not contain the manifest or version file, Nixpacks is inspecting a different project location. In a monorepo, correct the directory selection or move the version file to the directory actually used for the build.

Several files specify different versions

Conflicting manifests and version files make the build input ambiguous. Keep one authoritative value, update or remove stale files, and commit the result. If you intentionally need a deployment-specific value, use the Coolify build variable and document that it overrides the repository convention for that application.

The environment variable exists but has no effect

Edit the variable and verify that Build time is set to Available during build. A runtime-only variable cannot influence Nixpacks package selection. Save the change and create a new deployment so the image is rebuilt.

A restart still shows the old version

Restarting an existing image does not rerun Nixpacks. Trigger a deployment that performs a fresh build, then inspect that deployment’s log. If the old image is still being reused by your deployment process, confirm that the deployment actually reached the build phase.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The major line is correct but the patch changed

This is expected when the Nixpkgs archive supplying the package has changed. If the patch level is a hard requirement, add a verified nixpacks.toml archive pin or move to a Dockerfile with an exact base-image digest. Test the resulting package set because an archive pin also affects other Nix packages.

Nixpacks cannot provide the required image control

Use a Dockerfile when you need explicit operating-system packages, custom build stages, or an immutable base-image identity. A Dockerfile is more work to maintain, but it makes those choices visible and reviewable in the repository.

The build log does not show the version you expected

Return to the generated plan and the resolved package lines rather than relying on the value you entered. Confirm that the deployment used the intended commit, that the Base Directory was correct, and that the build-time variable was available when the image was created. If the plan still differs, remove stale competing files or add the appropriate nixpacks.toml configuration, then build again.

Practical policies for teams

For a conventional application

Put the supported major line in package.json or a committed version file, keep the Base Directory stable, and verify the resolved package after deployments. This keeps the version close to the code and lets Nixpacks handle routine image construction.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

For several deployment environments

Use NIXPACKS_NODE_VERSION when an environment-specific major line is intentional. Keep the variable marked for build-time availability and record its value with the deployment configuration so a repository checkout alone does not give a misleading picture of the build.

For strict reproducibility

Pin a tested Nixpkgs archive when you want Nixpacks to retain a complete package set. Choose a Dockerfile and an exact base-image digest when the requirement extends to image identity, operating-system packages, and build-stage behavior.

Whichever route you select, the verification loop is the same: make the source of truth unambiguous, rebuild the image, and confirm the resolved Node.js package in the build log.

Frequently Asked Questions

How do I set the Node.js version in Coolify?

For a Nixpacks application, set engines.node in package.json, add .nvmrc or .node-version in the Base Directory, or add NIXPACKS_NODE_VERSION in Configuration → Environment Variables. If you use the environment variable, mark it Available during build and redeploy.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Why is Coolify using the wrong Node.js version?

Check that the application is using Nixpacks, that the Base Directory contains the intended manifest or version file, and that duplicate files do not specify different values. For a dashboard setting, verify Build time is Available during build. Then create a new deployment and inspect the Nixpacks plan and build log.

Can I pin an exact Node.js patch version with Nixpacks?

A major value such as 22 does not pin a patch release. Add nixpacks.toml with a complete nixpkgsArchive commit SHA, verify that the selected archive contains the required Node.js package, and confirm the resolved version in the build log. The archive also changes other Nix packages and system libraries.

Will restarting the Coolify service apply a changed Node.js setting?

No. Node.js is selected while the image is built. A restart that reuses the existing image keeps its old package; deploy again so Nixpacks runs and produces a new image.

Should I use package.json or NIXPACKS_NODE_VERSION?

Use package.json or a committed version file when the Node.js line should travel with the repository. Use NIXPACKS_NODE_VERSION when separate Coolify applications or environments intentionally need different major lines. In either case, keep one documented authoritative value.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

When should I switch from Nixpacks to a Dockerfile?

Use a Dockerfile when you need explicit base-image identity, multiple build stages, operating-system packages, or image-level reproducibility. Use an exact base-image digest when immutable image identity is required, and maintain the Dockerfile’s dependency, build, and start steps yourself.

The Bottom Line

Choose one Node.js source of truth, make sure it is inside Coolify’s Base Directory, and redeploy after every build-time change. Nixpacks selectors choose a major line; a verified Nixpkgs archive pin controls the package set, while a Dockerfile with an exact base-image digest provides the broadest image-level control. Always verify the resolved version in the build log.

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.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
Crashes, No Sound, or Screen Glitches?Free driver scan
Windows Errors? Fix Them Before They SpreadFree repair scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.