Creating a Buildpack

​

Overview of a JavaScript Application

1. Entry Point (index.js):
   This file contains the main source code of your application. In our example, all the logic is contained in a single file, although larger projects may distribute the code across multiple files. The entry point is conventionally named index.js or app.js. To run the application, execute the following command:
   Copy

   Ask AI

   node index.js
   
   Below is a simple example using the Express framework:
   Copy

   Ask AI

   const express = require('express');
   const app = express();
   const PORT = process.env.PORT || 8080;
   
   // Define a route for the root URL
   app.get('/', (req, res) => {
     res.send('Hello, World!');
   });
   
   // Start the server
   app.listen(PORT, () => {
     console.log(`Server is running on http://localhost:${PORT}`);
   });
   
2. Package Configuration (package.json):
   The package.json file contains essential metadata about your project, including its dependencies. For instance, when using Express and UUID, your configuration might look like this:
   Copy

   Ask AI

   {
     "name": "example-application",
     "version": "1.0.0",
     "main": "index.js",
     "scripts": {
       "test": "echo \"Error: no test specified\" && exit 1"
     },
     "author": "",
     "license": "ISC",
     "description": "",
     "engines": {
       "node": "23.1.0"
     },
     "dependencies": {
       "express": "^4.21.1",
       "uuid": "^11.0.2"
     }
   }
   
   This file not only lists the dependencies but also specifies the required Node.js version for your application.
3. Lock File (package-lock.json):
   The package-lock.json locks dependencies to specific versions, ensuring consistency across development, CI/CD pipelines, and production environments. The buildpack later uses this file to detect any changes in dependency versions between builds.
4. Dependencies Folder (node_modules):
   After installing dependencies (for example, using npm), the node_modules folder contains the installed packages. A typical JavaScript project usually includes the entry point (index.js or app.js), the package configuration (package.json), and the node_modules directory.

​

Buildpack Files Overview

1. buildpack.toml:
   This configuration file defines metadata for your buildpack, such as the API version, buildpack ID, version, and target platform.
   Copy

   Ask AI

   api = "0.10"
   
   [buildpack]
     id = "my-js-buildpack"
     version = "0.0.1"
   
   [[targets]]
     os = "linux"
     arch = "amd64"
   
2. Detect Script (bin/detect):
   This executable script determines whether the buildpack should run. For a JavaScript buildpack, it checks for the presence of a package.json file. If the file is missing, the script exits with a status code of 100; otherwise, it allows the build process to continue.
   Copy

   Ask AI

   #!/usr/bin/env bash
   set -eo pipefail
   if [[ ! -f package.json ]]; then
     exit 100
   fi
   

3. Build Script (bin/build):
   This executable script transforms your application source code into a Docker (or OCI-compliant) image. Its tasks include setting environment variables, installing dependencies, compiling source code (if necessary), and configuring the application’s entry point. The Pack CLI offers a shortcut to generate this boilerplate. The following command creates a directory (in this example, js-buildpack) containing the buildpack.toml file and a bin folder with the detect and build scripts:
   Copy

   Ask AI

   pack buildpack new my-js-buildpack --api 0.10 --path js-buildpack --version 0.0.1
   
   The generated buildpack.toml will resemble:
   Copy

   Ask AI

   api = "0.10"
   
   [buildpack]
     id = "my-js-buildpack"
     version = "0.0.1"
   
   [[targets]]
     os = "linux"
     arch = "amd64"
   

​

Detailed Look at the Detect Script

#!/usr/bin/env bash
set -eo pipefail
if [[ ! -f package.json ]]; then
  exit 100
fi

​

Detailed Look at the Build Script

1. Installing Node.js:
   The script downloads and extracts Node.js from its official distribution URL.
2. Installing Application Dependencies:
   It then uses either npm ci or npm install to install all dependencies specified in both package.json and package-lock.json.
3. Configuring the Application Entry Point:
   The script creates a launch.toml file in the directory defined by the CNB_LAYERS_DIR environment variable. This file specifies the command that will run when the container is started.

#!/usr/bin/env bash
set -eo pipefail

echo "---> Building image using my-js-buildpack buildpack"
node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
wget -q -O - "$node_js_url" | tar -xJf - --strip-components 1

export PATH="./bin:$PATH"

echo "---> Installing Application Dependencies"
npm ci

cat > "${CNB_LAYERS_DIR}/launch.toml" << EOL
[[processes]]
type = "web"
command = ["bin/node", "index.js"]
default = true
EOL

​

Building the Application Image

pack build myapp --path ./nodejs/ --buildpack ./js-buildpack/ --builder cnbs/sample-builder:jamm

• myapp represents the name of the generated image.
• --path ./nodejs/ specifies the directory containing your application’s source code.
• --buildpack ./js-buildpack/ points to the folder containing your custom buildpack.
• --builder cnbs/sample-builder:jamm indicates which builder to use (note that the builder will override its default buildpacks with the buildpack you specified).