Creating Node.js Code-only Functions

Node.js archive requirements

For Node.js code-only functions:

• The archive must contain a root-level function/ directory.
• The function/ directory contains the handler file and application source code.
• The root-level node_modules/ directory is optional. Include it only when the function has Node.js dependencies.
• The root-level resources/ directory is optional and contains runtime resources.
• The root-level native/ directory is optional only for multi-architecture native dependency use cases.
• For single-architecture Node.js functions, root-level native/ is not allowed.
• For single-architecture Node.js functions with native dependencies, package native dependencies directly under node_modules/.
• For multi-architecture Node.js functions, if native/ exists, place architecture-specific native dependency files only under native/fn-arch-x86/ and native/fn-arch-arm/.
• A handler is required.

Node.js handler

The handler tells OCI Functions which JavaScript file to invoke.

Example handler:

func.js

Single-architecture Node.js archive

archive-root/
├── function/
    └── func.js
├── node_modules/  # optional
└── resources/     # optional

Rules:

• function/ is required.
• node_modules/ is optional.
• resources/ is optional.
• native/ is not allowed for single-architecture Node.js functions.
• For single-architecture native dependencies, package the dependency under node_modules/.
• The handler must refer to a JavaScript file in the function/ directory.

Package Node.js source without dependencies

mkdir -p build/archive/function
cp func.js build/archive/function/
cd build/archive
zip -r ../function.zip function/

Handler:

func.js

Package Node.js source with dependencies

mkdir -p build/archive/function

cp func.js build/archive/function/

cp package.json package-lock.json build/archive/

cd build/archive

npm ci --omit=dev

zip -r ../function.zip function/ node_modules/

If using resources, include resources/ at the archive root.

Dependency packaging

OCI Functions does not download Node.js dependencies during function creation. Package required dependencies in the archive before creating or updating the function.

Node.js archive with native dependencies

Node.js functions can depend on packages that include compiled native code, such as .node binaries or native add-ons built with tools such as node-gyp.

For single-architecture Node.js functions:

• Do not include root-level native/.
• Package native dependencies directly under node_modules/.
• Make sure dependencies are built for the correct Linux platform and architecture.

For multi-architecture Node.js functions:

• Package source under function/.
• Package shared dependencies under node_modules/, if needed.
• Package architecture-specific native dependencies under:
  • native/fn-arch-x86/
  • native/fn-arch-arm/

archive-root/
├── function/
    └── func.js
├── node_modules/  # optional
├── resources/     # optional
└── native/
    ├── fn-arch-x86/
    └── fn-arch-arm/

Rules:

• native/ is required only if the function uses architecture-specific native dependencies in a multi-architecture application.
• If native/ exists for a multi-architecture application, it must contain both fn-arch-x86/ and fn-arch-arm/.
• Place native dependency files only under the matching architecture directory.
• node_modules/ can still be used for non-native or shared dependencies.
• function/ is always required.

Node.js runtime behavior

The Node.js FDK is included in the managed Node.js runtime for code-only functions. Package the handler file, application code, and any required dependencies in the archive.

Creating a Node.js code-only function

Use the shared code-only functions creation steps. Select a supported Node.js runtime, enter the Node.js handler, and provide the Node.js archive.

The Node.js function is created and can be invoked like any other function.

To create a Node.js code-only function, follow the instructions in Creating Code-only Functions. For example, to create a Node.js code-only function using the Console:

1. On the Applications list page, select the application in which you want to create the Node.js code-only function. If you need help finding the list page or the application, see Listing Applications.

2. Select the Functions tab.

   The Functions list page opens. All functions in the selected application are displayed in a table.

3. Select Create from archive and specify details for the Node.js code-only function, including the file source, the Node.js archive, a supported Node.js runtime, and a Node.js handler.

   For Node.js code-only functions, you must specify a handler when you create the function.

4. Specify other details for the function as required (see Creating Code-only Functions).
5. Select Create to create the function.

   The Node.js code-only function is created and can be invoked like any other function.

Troubleshooting