{"id":12725,"library":"esbuild-linux-64","title":"esbuild Linux 64-bit Binary","description":"This package, `esbuild-linux-64`, provides the native 64-bit Linux binary for esbuild, an extremely fast JavaScript and CSS bundler and minifier. Esbuild is renowned for its exceptional speed, often completing builds 10-100 times faster than alternatives like Webpack or Rollup, attributed to its implementation in Go and heavy use of parallelism. It supports modern JavaScript features, TypeScript, JSX, tree-shaking, and has a simple, intuitive API. While `esbuild-linux-64` itself is a low-level component, the overarching `esbuild` project (currently at v0.28.0 as of April 2026) maintains a very active release cadence, frequently publishing updates with new features, bug fixes, and performance improvements. It is widely adopted by tools like Vite, Angular (since v17), and Ruby on Rails (since v7) for its performance. The package's purpose is to be an automatically selected optional dependency of the main `esbuild` package, providing the correct native executable for Linux x64 environments.","status":"active","version":"0.15.18","language":"javascript","source_language":"en","source_url":"https://github.com/evanw/esbuild","tags":["javascript"],"install":[{"cmd":"npm install esbuild-linux-64","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-linux-64","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-linux-64","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package (`esbuild-linux-64`) is a native binary and is NOT directly imported into JavaScript/TypeScript code. Users interact with the high-level `esbuild` package, which orchestrates the use of the appropriate platform-specific binary at runtime. Do not attempt to import from `esbuild-linux-64` directly.","wrong":"import { build } from 'esbuild-linux-64'","symbol":"build","correct":"import { build } from 'esbuild'"},{"note":"The `context` API is used for incremental builds and watch mode. All programmatic interactions with esbuild, including context creation, are done through the main `esbuild` package. Avoid CommonJS `require` if targeting ESM or using modern Node.js environments.","wrong":"const context = require('esbuild-linux-64');","symbol":"context","correct":"import { context } from 'esbuild'"},{"note":"The `serve` API provides a development server. As with other esbuild APIs, it is exposed by the main `esbuild` package, not the platform-specific binary package. Incorrectly trying to `require` the binary package directly will result in a 'Cannot find module' error.","wrong":"const { serve } = require('@esbuild/linux-x64');","symbol":"serve","correct":"import { serve } from 'esbuild'"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport { readFileSync, writeFileSync } from 'fs';\nimport { resolve } from 'path';\n\nconst entryPoint = resolve(__dirname, 'src/index.ts');\nconst outFile = resolve(__dirname, 'dist/bundle.js');\n\nasync function runBuild() {\n  try {\n    await build({\n      entryPoints: [entryPoint],\n      bundle: true,\n      minify: true,\n      sourcemap: true,\n      platform: 'node',\n      target: 'es2020',\n      outfile: outFile,\n      logLevel: 'info',\n      // This is crucial: esbuild-linux-64 is an *optional dependency* of 'esbuild'.\n      // 'esbuild' detects your platform and uses the correct binary.\n      // You typically just install 'esbuild' and it handles the rest.\n    });\n    console.log(`Build successful: ${outFile}`);\n    \n    // Example of reading the output for verification\n    const bundledCode = readFileSync(outFile, 'utf-8');\n    console.log(`Bundled code starts with:\\n${bundledCode.substring(0, 100)}...`);\n\n  } catch (error) {\n    console.error('Build failed:', error);\n    process.exit(1);\n  }\n}\n\n// To make this runnable, ensure a dummy src/index.ts exists:\n// mkdir -p src && echo 'console.log(\"Hello from esbuild!\");' > src/index.ts\n\nrunBuild();","lang":"typescript","description":"Demonstrates a basic esbuild bundling and minification process using its JavaScript API, highlighting how the main `esbuild` package abstracts away platform-specific binaries like `esbuild-linux-64`."},"warnings":[{"fix":"Pin the `esbuild` package version in `package.json` (e.g., `\"esbuild\": \"0.28.0\"`) or use `~` for patch updates (e.g., `\"esbuild\": \"~0.28.0\"`). Regularly review the changelog before upgrading.","message":"Esbuild releases, particularly major versions (e.g., v0.27.0), often contain backwards-incompatible changes. Users are strongly advised to pin exact versions or use patch-only version ranges (e.g., `^0.26.0`, `~0.26.0`) in `package.json` to prevent unexpected breakages during updates.","severity":"breaking","affected_versions":">=0.17.0"},{"fix":"Ensure `npm install` runs within the target environment (e.g., inside the Docker container), rather than copying `node_modules` from a different OS/architecture. Add `node_modules` to `.dockerignore`. Alternatively, consider `esbuild-wasm` for full platform portability, though with a performance penalty.","message":"Using platform-specific binaries like `esbuild-linux-64` in cross-platform environments (e.g., developing on macOS/Windows and deploying to a Linux Docker container) can lead to 'platform mismatch' errors.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure your Node.js environment is version 18 or later. Update Node.js if necessary. The `engines` field `\"node\": \">=12\"` in `esbuild-linux-64`'s `package.json` may be outdated or refer to older core compatibility.","message":"Esbuild's minimum Node.js version requirement for its JavaScript API increased from Node 12 to Node 18 (as of `0.23.0` in 2024). Running esbuild with older Node.js versions will result in incompatibilities.","severity":"breaking","affected_versions":">=0.23.0"},{"fix":"When bundling for Node.js (`--platform=node`), generally use `--format=cjs` for maximum compatibility with npm packages. If using ESM, be aware of Node.js's CJS/ESM interoperability limitations and potential need for polyfills for features like top-level await.","message":"Mixing CommonJS (CJS) and ES Modules (ESM) in a Node.js project bundled with esbuild can lead to interoperability issues, especially with dynamic imports or complex `exports` maps in `package.json`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure the underlying Linux operating system meets the minimum kernel version requirements. For specific `Uint8Array.fromBase64` usage with Node, you might need to specify a target like `--target=node22` if not on Node v25+.","message":"As of v0.27.0, esbuild's binary loader uses `Uint8Array.fromBase64` if available, and specific Go compiler updates (e.g., Go 1.26 in `v0.28.0`) have raised minimum operating system requirements for esbuild binaries. For Linux, a kernel version of 3.2 or later is now required.","severity":"breaking","affected_versions":">=0.27.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Remove `node_modules` and `package-lock.json` (or `yarn.lock`) and run `npm install` (or `yarn install`) directly within the target environment (e.g., inside the Docker container). Make sure `node_modules` is excluded from copy operations in your deployment pipeline.","cause":"The `esbuild` main package detected a platform-specific binary (e.g., `esbuild-darwin-arm64`) that does not match the current operating system and architecture (e.g., running in a Linux container). This often happens when `node_modules` is copied between different environments.","error":"Error: You installed esbuild on another platform than the one you're currently using."},{"fix":"Import `esbuild` instead of `esbuild-linux-64`. The main `esbuild` package dynamically loads the correct platform-specific binary. For example: `import { build } from 'esbuild';`.","cause":"Attempting to directly `import` or `require` the `esbuild-linux-64` package from JavaScript/TypeScript code. This package is a native binary, not a JavaScript module for direct consumption.","error":"Error: Cannot find module 'esbuild-linux-64'"},{"fix":"Ensure `esbuild` (the main package) is installed correctly, typically as a `devDependency`. Use `npx esbuild` to run the local CLI, or ensure `$(npm bin)` is in your PATH. If `esbuild-linux-64` was installed standalone, it won't provide the `esbuild` CLI command directly, you need the main `esbuild` package.","cause":"The `esbuild` executable is not in the system's PATH, or the installation of the main `esbuild` package (which manages the binary) failed to link correctly, or `esbuild-linux-64` was installed without the main `esbuild` package.","error":"esbuild: command not found"},{"fix":"Adjust the `--target` option in your esbuild configuration (e.g., `--target=es2022` or `--target=node18`) to match your intended runtime environment. Ensure your Node.js version meets esbuild's minimum requirements, especially for recent features.","cause":"Esbuild's output target (`--target`) is set to an environment that does not support certain language features used in the source code, or a Node.js version older than required is being used. This could be due to `Uint8Array.fromBase64` not being available or other syntax incompatibilities.","error":"Unsupported target environment"}],"ecosystem":"npm"}