npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@netlify/zip-it-and-ship-it

v9.30.0

Published

Zip it and ship it

Downloads

908,823

Readme

zip-it-and-ship-it

npm version Coverage Status Build Downloads

Creates Zip archives from Node.js, Go, and Rust programs. Those archives are ready to be uploaded to AWS Lambda.

This library is used under the hood by several Netlify features, including production CI builds, Netlify CLI and the JavaScript client.

Check Netlify documentation for:

Installation

npm install @netlify/zip-it-and-ship-it

Usage (Node.js)

zipFunctions(srcFolders, destFolder, options?)

  • srcFolders: string | Array<string>
  • destFolder: string
  • options: object?
  • Return value: Promise<object[]>
import { zipFunctions } from '@netlify/zip-it-and-ship-it'

const archives = await zipFunctions('functions', 'functions-dist', {
  archiveFormat: 'zip',
})

Creates Zip archives from Node.js, Go, and Rust programs. Those archives are ready to be uploaded to AWS Lambda.

srcFolders

A directory or a list of directories containing the source files. If a string is provided, the corresponding directory must exist. If an array of strings is provided, at least one directory must exist.

In Netlify, this directory is the "Functions folder".

A source folder can contain:

  • Sub-directories with a main file called index.js or {dir}.js where {dir} is the sub-directory name.
  • .js, .mjs, .cjs, .ts, .tsx, .mts or .cts files (Node.js)
  • .zip archives with Node.js already ready to upload to AWS Lambda.
  • Go programs already compiled. Those are copied as is.
  • Rust programs already compiled. Those are zipped.

destFolder

The directory where each .zip archive should be output. It is created if it does not exist. In Netlify CI, this is an unspecified temporary directory inside the CI machine. In Netlify CLI, this is a .netlify/functions directory in your build directory.

options

An optional object for customizing the behavior of the archive creation process.

archiveFormat

  • Type: string
  • Default value: zip

Format of the archive created for each function. Defaults to ZIP archives.

If set to none, the output of each function will be a directory containing all the bundled files.

basePath

  • Type: string
  • Default value: undefined

The directory which all relative paths will be resolved from. These include paths in the includedFiles config property, as well as imports using dynamic expressions such as require(\./files/${name}`)`.

config

  • Type: object
  • Default value: {}

An object matching glob-like expressions to objects containing configuration properties. Whenever a function name matches one of the expressions, it inherits the configuration properties.

The following properties are accepted:

  • externalNodeModules

    • Type: array<string>

    List of Node modules to include separately inside a node_modules directory.

  • ignoredNodeModules

    • Type: array<string>

    List of Node modules to keep out of the bundle.

  • nodeBundler

    • Type: string
    • Default value: zisi

    The bundler to use when processing JavaScript functions. Possible values: zisi, esbuild, esbuild_zisi or nft.

    When the value is esbuild_zisi, esbuild will be used with a fallback to zisi in case of an error.

  • nodeSourcemap

    • Type: boolean
    • Default value: false

    Whether to include a sourcemap file in the generated archive.

    Available only when nodeBundler is set to esbuild or esbuild_zisi.

  • nodeVersion

    • Type: string\
    • Default value: 18

    The version of Node.js to use as the compilation target for bundlers. This is also used to determine the runtime reported in the manifest. Any valid and supported Node.js version is accepted. Examples:

    • 14.x
    • 16.1.0
    • v18
    • nodejs18.x (for backwards compatibility)
  • rustTargetDirectory

    • Type: string
    • Default value: Path to a temporary directory

    The path to use as the Cargo target directory when bundling Rust functions from source. When a value is not specified, a random temporary directory will be used.

    The [name] placeholder will be replaced by the name of the function, allowing you to use it to construct the path to the target directory.

  • name

    • Type: string
    • Default value: undefined

    A name to use when displaying the function in the Netlify UI. Populates the displayName property in the functions manifest for the specified function.

  • generator

    • Type: string
    • Default value: undefined

    A field to use if the function has been autogenerated by a plugin or integration. A recommended format is @netlify/[email protected], where adding the version is highly appreciated.

featureFlags

See feature flags.

manifest

  • Type: string
  • Default value: undefined

Defines the full path, including the file name, to use for the manifest file that will be created with the functions bundling results. For example, path/to/manifest.json. This file is a JSON-formatted string with the following properties:

  • functions: An array with the functions created, in the same format as returned by zipFunctions
  • system.arch: The operating system CPU architecture, as returned by process.arch
  • system.platform: The operating system, as returned by process.platform
  • timestamp: The timestamp (in milliseconds) at the time of the functions bundling process
  • version: The version of the manifest file (current version is 1)

parallelLimit

  • Type: number
  • Default value: 5

Maximum number of functions to bundle at the same time.

internalSrcFolder

  • Type: string
  • Default value: undefined

Defines the path to the folder with internal functions. Used to populate a function's generator property if generator is not configured in the function's config itself, if its path is within this specified internal functions folder.

Return value

This returns a Promise resolving to an array of objects describing each archive. Every object has the following properties.

  • mainFile: string

    The path to the function's entry file.

  • name: string

    The name of the function.

  • path: string

    Absolute file path to the archive file.

  • runtime string

    Either "js", "go", or "rs".

  • size: number

    The size of the generated archive, in bytes.

  • displayName: string

    If there was a user-defined configuration object applied to the function, and it had a name defined. This will be returned here.

  • generator: string

    If there was a user-defined configuration object applied to the function, and it had generator defined. This will be returned here. If there was nothing defined, but an internalSrcFolder was passed and the function was defined in there, it will return a string to specify it was an internal function.

Additionally, the following properties also exist for Node.js functions:

  • bundler: string

    Contains the name of the bundler that was used to prepare the function.

  • bundlerErrors: Array<object>

    Contains any errors that were generated by the bundler when preparing the function.

  • bundlerWarnings: Array<object>

    Contains any warnings that were generated by the bundler when preparing the function.

  • config: object

    The user-defined configuration object that was applied to a particular function.

  • inputs: Array<string>

    A list of file paths that were visited as part of the dependency traversal. For example, if my-function.js contains require('./my-supporting-file.js'), the inputs array will contain both my-function.js and my-supporting-file.js.

  • nativeNodeModules: object

    A list of Node modules with native dependencies that were found during the module traversal. This is a two-level object, mapping module names to an object that maps the module path to its version. For example:

    {
      "nativeNodeModules": {
        "module-one": {
          "/full/path/to/the/module": "1.0.0",
          "/another/instance/of/this/module": "2.0.0"
        }
      }
    }
  • runtimeAPIVersion number | undefined

    When a function with the new API will be detected this is set to 2. Otherwise it is set to 1. undefined is only returned in case of an error.

  • runtimeVersion string | undefined

    Which exact runtime this function should be using. (e.g. nodejs18.x). This value is detected based on the input nodeVersion.

zipFunction(srcPath, destFolder, options?)

  • srcPath: string
  • destFolder: string
  • options: object?
  • Return value: object | undefined
import { zipFunction } from '@netlify/zip-it-and-ship-it'

const archive = await zipFunction('functions/function.js', 'functions-dist')

This is like zipFunctions() except it bundles a single Function.

The return value is undefined if the function is invalid.

listFunctions(srcFolders, options?)

Returns the list of functions to bundle.

import { listFunctions } from '@netlify/zip-it-and-ship-it'

const functions = await listFunctions('functions/function.js')

srcFolders

A directory or a list of directories containing the source files. If a string is provided, the corresponding directory must exist. If an array of strings is provided, at least one directory must exist.

options

An optional options object.

featureFlags

See feature flags.

Return value

Each object has the following properties:

  • name: string

    Function's name. This is the one used in the Function URL. For example, if a Function is a myFunc.js regular file, the name is myFunc and the URL is https://{hostname}/.netlify/functions/myFunc.

  • displayName: string

    If there was a user-defined configuration object applied to the function, and it had a name defined. This will be returned here.

  • mainFile: string

    Absolute path to the Function's main file. If the Function is a Node.js directory, this is its index.js or {dir}.js file.

  • runtime: string

    Either "js", "go", or "rs".

  • extension: string

    Source file extension. For Node.js, this is either .js, .ts or .zip. For Go, this can be anything.

  • generator: string

    If there was a user-defined configuration object applied to the function, and it had generator defined. This will be returned here.

listFunctionsFiles(srcFolders)

Like listFunctions(), except it returns not only the Functions main files, but also all their required files. This is much slower.

import { listFunctionsFiles } from '@netlify/zip-it-and-ship-it'

const functions = await listFunctionsFiles('functions/function.js')

srcFolders

A directory or a list of directories containing the source files. If a string is provided, the corresponding directory must exist. If an array of strings is provided, at least one directory must exist.

options

An optional options object.

featureFlags

See feature flags.

Return value

The return value is the same as listFunctions() but with the following additional properties.

  • srcFile: string

    Absolute file to the source file.

Usage (CLI)

$ zip-it-and-ship-it srcFolder destFolder

The CLI performs the same logic as zipFunctions(). The archives are printed on stdout as a JSON array.

Bundling Node.js functions

zip-it-and-ship-it uses two different mechanisms (bundlers) for preparing Node.js functions for deployment. You can choose which one to use for all functions or on a per-function basis.

zisi

This is the default bundler.

When using the zisi bundler, the following files are included in the generated archive:

  • All files/directories within the same directory (except node_modules)
  • All the files referenced using static require() calls
    • Example (user file): require('./lib/my-file')
    • Example (Node module): require('date-fns')

The following files are excluded:

  • @types/* TypeScript definitions
  • aws-sdk (on Node v16 and earlier)
  • @aws-sdk/* (on Node v18 and later)
  • Temporary files like *~, *.swp, etc.

esbuild

The esbuild bundler can generate smaller archives due to its tree-shaking step. It's also a lot faster. You can read more about it on the Netlify Blog.

When using esbuild, only the files that are directly required by a function or one of its dependencies will be included. For example, a Node module has 1,000 files but your function only requires one of them, the other 999 will not be included in the bundle.

You can enable esbuild by setting the config option when calling zipFunction or zipFunctions:

import { zipFunctions } from '@netlify/zip-it-and-ship-it'

const archives = await zipFunctions('functions', 'functions-dist', {
  config: {
    // Applying these settings to all functions.
    '*': {
      nodeBundler: 'esbuild',
    },
  },
})

Feature flags

zip-it-and-ship-it uses feature flags to enable or disable features during their testing or deprecation periods.

These are supplied to each of the entrypoint functions (zipFunction, zipFunctions, listFunctions and listFunctionsFiles) as a named parameter called featureFlags. It consists of an object where each key is the name of a feature flag and the values are Booleans indicating whether each feature flag is enabled or disabled.

The list of all feature flags currently being used can be found here.

Troubleshooting

Build step

zip-it-and-ship-it does not build, transpile nor install the dependencies of the Functions. This needs to be done before calling zip-it-and-ship-it.

Missing dependencies

If a Node module require() another Node module but does not list it in its package.json (dependencies, peerDependencies or optionalDependencies), it is not bundled, which might make the Function fail.

More information in this issue.

Conditional require

Files required with a require() statement inside an if or try/catch block are always bundled.

More information in this issue.

Dynamic require

Files required with a require() statement whose argument is not a string literal, e.g. require(variable), are never bundled.

More information in this issue.

Node.js native modules

If your Function or one of its dependencies uses Node.js native modules, the Node.js version used in AWS Lambda might need to be the same as the one used when installing those native modules.

In Netlify, this is done by ensuring that the following Node.js versions are the same:

Note that this problem might not apply for Node.js native modules using the N-API.

More information in this issue.

File Serving

As of v0.3.0 the serveFunctions capability has been extracted out to Netlify Dev.