npminstall

README

Paketo Buildpack for NPM Install

The NPM Install CNB makes use of the npm tooling installed within the Node Engine CNB to manage application dependencies.

Integration

The NPM Install CNB provides node_modules as a dependency. Downstream buildpacks can require the node_modules dependency by generating a Build Plan TOML file that looks like the following:

[[requires]]

  # The name of the NPM Install dependency is "node_modules". This value is
  # considered part of the public API for the buildpack and will not change
  # without a plan for deprecation.
  name = "node_modules"

  # Note: The version field is unsupported as there is no version for a set of
  # npm.

  # The NPM Install buildpack supports some non-required metadata options.
  [requires.metadata]

    # Setting the build flag to true will ensure that the node modules are
    # available for subsequent buildpacks during their build phase.
    # If you are writing a buildpack that needs to run a node module during its build
    # process, this flag should be set to true.
    build = true

    # Setting the launch flag to true will ensure that the packages managed by
    # NPM will be available for the running application. If you
    # are writing an application that needs to run node modules at runtime, this
    # flag should be set to true.
    launch = true

Configuration

Environment Variable	Description
$BP_NPM_VERSION	If set, this custom version of npm will be used instead of the one provided by the nodejs installation.
$BP_KEEP_NODE_BUILD_CACHE	If set to true (default false), the folder node_modules/.cache will not be removed after the build, but will be readonly at runtime.

Usage

To package this buildpack for consumption:

$ ./scripts/package.sh --version <version-number>

This will create a buildpackage.cnb file under the build directory which you can use to build your app as follows: pack build <app-name> -p <path-to-app> -b <path/to/node-engine.cnb> -b build/buildpackage.cnb

Specifying a project path

To specify a project subdirectory to be used as the root of the app, please use the BP_NODE_PROJECT_PATH environment variable at build time either directly (e.g. pack build my-app --env BP_NODE_PROJECT_PATH=./src/my-app) or through a project.toml file. This could be useful if your app is a part of a monorepo.

Run Tests

To run all unit tests, run:

./scripts/unit.sh

To run all integration tests, run:

/scripts/integration.sh

Stack support

For most apps, the NPM Install Buildpack runs fine on the Base builder. But when the app requires compilation of native extensions using node-gyp, the buildpack requires that you use the Full builder. This is because node-gyp requires python that's absent on the Base builder, and the module may require other shared objects.

Documentation

Index

• Constants
• func Build(entryResolver EntryResolver, configurationManager ConfigurationManager, ...) packit.BuildFunc
• func Detect() packit.DetectFunc
• func UpdateNpmCacheLayer(logger scribe.Emitter, workingDir string, cacheLayer packit.Layer) (packit.Layer, error)
• type BindingResolver
• type BuildManager
• type BuildPlanMetadata
• type BuildProcess
• type BuildProcessResolver
  • func NewBuildProcessResolver(logger scribe.Logger, rebuild, install, ci BuildProcess) BuildProcessResolver
  • func (r BuildProcessResolver) Resolve(workingDir string) (BuildProcess, bool, error)
• type CIBuildProcess
  • func NewCIBuildProcess(executable Executable, summer Summer, environment EnvironmentConfig, ...) CIBuildProcess
  • func (r CIBuildProcess) Run(modulesDir, cacheDir, workingDir, npmrcPath string, launch bool) error
  • func (r CIBuildProcess) ShouldRun(workingDir string, metadata map[string]interface{}, npmrcConfig string) (bool, string, error)
• type ConfigurationManager
• type EntryResolver
• type Environment
  • func ParseEnvironment(path string, variables []string) (Environment, error)
  • func (e Environment) Lookup(key string) (string, bool)
  • func (e Environment) LookupBool(key string) (bool, error)
• type EnvironmentConfig
• type Executable
• type InstallBuildProcess
  • func NewInstallBuildProcess(executable Executable, environment EnvironmentConfig, logger scribe.Logger) InstallBuildProcess
  • func (r InstallBuildProcess) Run(modulesDir, cacheDir, workingDir, npmrcPath string, launch bool) error
  • func (r InstallBuildProcess) ShouldRun(workingDir string, metadata map[string]interface{}, npmrcPath string) (bool, string, error)
• type LinkedModuleResolver
  • func NewLinkedModuleResolver(linker Symlinker) LinkedModuleResolver
  • func (r LinkedModuleResolver) Copy(lockfilePath, sourceLayerPath, targetLayerPath string) error
  • func (r LinkedModuleResolver) ParseLockfile(lockfilePath string) (Lockfile, error)
  • func (r LinkedModuleResolver) Resolve(lockfilePath, layerPath string) error
• type Linker
  • func NewLinker(tmpDir string) Linker
  • func (l Linker) Link(source, target string) error
  • func (l Linker) WithPath(path string) Symlinker
• type Lockfile
• type PackageManagerConfigurationManager
  • func NewPackageManagerConfigurationManager(bindingResolver BindingResolver, logs scribe.Emitter, defaultPath string) PackageManagerConfigurationManager
  • func (p PackageManagerConfigurationManager) DeterminePath(typ, platformDir, entry string) (string, error)
• type PruneBuildProcess
  • func NewPruneBuildProcess(executable Executable, environment EnvironmentConfig, logger scribe.Logger) PruneBuildProcess
  • func (r PruneBuildProcess) Run(modulesDir, cacheDir, workingDir, npmrcPath string, launch bool) error
  • func (r PruneBuildProcess) ShouldRun(workingDir string, metadata map[string]interface{}, npmrcPath string) (bool, string, error)
• type PruneProcess
• type RebuildBuildProcess
  • func NewRebuildBuildProcess(executable Executable, summer Summer, environment EnvironmentConfig, ...) RebuildBuildProcess
  • func (r RebuildBuildProcess) Run(modulesDir, cacheDir, workingDir, npmrcPath string, launch bool) error
  • func (r RebuildBuildProcess) ShouldRun(workingDir string, metadata map[string]interface{}, npmrcPath string) (bool, string, error)
• type SBOMGenerator
• type Summer
• type SymlinkResolver
• type Symlinker
• type VersionParser

Constants

const (
	NodeModules = "node_modules"
	Node        = "node"
	Npm         = "npm"

	LayerNameNodeModules = "modules"
	LayerNameCache       = "npm-cache"
)

const NODE_MODULES_CACHE = "node_modules_cache"

Functions

func Build

func Build(entryResolver EntryResolver,
	configurationManager ConfigurationManager,
	buildManager BuildManager,
	pruneProcess PruneProcess,
	clock chronos.Clock,
	logger scribe.Emitter,
	sbomGenerator SBOMGenerator,
	linker Symlinker,
	environment EnvironmentConfig,
	symlinkResolver SymlinkResolver,
) packit.BuildFunc

func Detect

func Detect() packit.DetectFunc

func UpdateNpmCacheLayer

func UpdateNpmCacheLayer(logger scribe.Emitter, workingDir string, cacheLayer packit.Layer) (packit.Layer, error)

Types

type BindingResolver

type BindingResolver interface {
	Resolve(typ, provider, platformDir string) ([]servicebindings.Binding, error)
}

type BuildManager

type BuildManager interface {
	Resolve(workingDir string) (BuildProcess, bool, error)
}

type BuildPlanMetadata

type BuildPlanMetadata struct {
	Version       string `toml:"version"`
	VersionSource string `toml:"version-source"`
	Build         bool   `toml:"build"`
	Launch        bool   `toml:"launch"`
}

type BuildProcess

type BuildProcess interface {
	ShouldRun(workingDir string, metadata map[string]interface{}, npmrcPath string) (run bool, sha string, err error)
	Run(modulesDir, cacheDir, workingDir, npmrcPath string, launch bool) error
}

type BuildProcessResolver

type BuildProcessResolver struct {
	// contains filtered or unexported fields
}

func NewBuildProcessResolver

func NewBuildProcessResolver(logger scribe.Logger, rebuild, install, ci BuildProcess) BuildProcessResolver

func (BuildProcessResolver) Resolve

func (r BuildProcessResolver) Resolve(workingDir string) (BuildProcess, bool, error)

type CIBuildProcess

type CIBuildProcess struct {
	// contains filtered or unexported fields
}

func NewCIBuildProcess

func NewCIBuildProcess(executable Executable, summer Summer, environment EnvironmentConfig, logger scribe.Logger) CIBuildProcess

func (CIBuildProcess) Run

func (r CIBuildProcess) Run(modulesDir, cacheDir, workingDir, npmrcPath string, launch bool) error

func (CIBuildProcess) ShouldRun

func (r CIBuildProcess) ShouldRun(workingDir string, metadata map[string]interface{}, npmrcConfig string) (bool, string, error)

type ConfigurationManager

type ConfigurationManager interface {
	DeterminePath(typ, platformDir, entry string) (path string, err error)
}

type EntryResolver

type EntryResolver interface {
	MergeLayerTypes(string, []packit.BuildpackPlanEntry) (launch, build bool)
}

type Environment

type Environment struct {
	// contains filtered or unexported fields
}

func ParseEnvironment

func ParseEnvironment(path string, variables []string) (Environment, error)

func (Environment) Lookup

func (e Environment) Lookup(key string) (string, bool)

func (Environment) LookupBool

func (e Environment) LookupBool(key string) (bool, error)

type EnvironmentConfig

type EnvironmentConfig interface {
	Lookup(key string) (value string, found bool)
	LookupBool(key string) (bool, error)
}

type Executable

type Executable interface {
	Execute(pexec.Execution) (err error)
}

type InstallBuildProcess

type InstallBuildProcess struct {
	// contains filtered or unexported fields
}

func NewInstallBuildProcess

func NewInstallBuildProcess(executable Executable, environment EnvironmentConfig, logger scribe.Logger) InstallBuildProcess

func (InstallBuildProcess) Run

func (r InstallBuildProcess) Run(modulesDir, cacheDir, workingDir, npmrcPath string, launch bool) error

func (InstallBuildProcess) ShouldRun

func (r InstallBuildProcess) ShouldRun(workingDir string, metadata map[string]interface{}, npmrcPath string) (bool, string, error)

type LinkedModuleResolver

type LinkedModuleResolver struct {
	// contains filtered or unexported fields
}

func NewLinkedModuleResolver

func NewLinkedModuleResolver(linker Symlinker) LinkedModuleResolver

func (LinkedModuleResolver) Copy

func (r LinkedModuleResolver) Copy(lockfilePath, sourceLayerPath, targetLayerPath string) error

func (LinkedModuleResolver) ParseLockfile

func (r LinkedModuleResolver) ParseLockfile(lockfilePath string) (Lockfile, error)

func (LinkedModuleResolver) Resolve

func (r LinkedModuleResolver) Resolve(lockfilePath, layerPath string) error

type Linker

type Linker struct {
	// contains filtered or unexported fields
}

func NewLinker

func NewLinker(tmpDir string) Linker

func (Linker) Link

func (l Linker) Link(source, target string) error

func (Linker) WithPath

func (l Linker) WithPath(path string) Symlinker

type Lockfile

type Lockfile struct {
	Packages map[string]struct {
		Resolved string `json:"resolved"`
		Link     bool   `json:"link"`
	} `json:"packages"`
}

type PackageManagerConfigurationManager

type PackageManagerConfigurationManager struct {
	// contains filtered or unexported fields
}

func NewPackageManagerConfigurationManager

func NewPackageManagerConfigurationManager(bindingResolver BindingResolver, logs scribe.Emitter, defaultPath string) PackageManagerConfigurationManager

func (PackageManagerConfigurationManager) DeterminePath

func (p PackageManagerConfigurationManager) DeterminePath(typ, platformDir, entry string) (string, error)

type PruneBuildProcess

type PruneBuildProcess struct {
	// contains filtered or unexported fields
}

func NewPruneBuildProcess

func NewPruneBuildProcess(executable Executable, environment EnvironmentConfig, logger scribe.Logger) PruneBuildProcess

func (PruneBuildProcess) Run

func (r PruneBuildProcess) Run(modulesDir, cacheDir, workingDir, npmrcPath string, launch bool) error

func (PruneBuildProcess) ShouldRun

func (r PruneBuildProcess) ShouldRun(workingDir string, metadata map[string]interface{}, npmrcPath string) (bool, string, error)

type PruneProcess

type PruneProcess interface {
	ShouldRun(workingDir string, metadata map[string]interface{}, npmrcPath string) (run bool, sha string, err error)
	Run(modulesDir, cacheDir, workingDir, npmrcPath string, launch bool) error
}

type RebuildBuildProcess

type RebuildBuildProcess struct {
	// contains filtered or unexported fields
}

func NewRebuildBuildProcess

func NewRebuildBuildProcess(executable Executable, summer Summer, environment EnvironmentConfig, logger scribe.Logger) RebuildBuildProcess

func (RebuildBuildProcess) Run

func (r RebuildBuildProcess) Run(modulesDir, cacheDir, workingDir, npmrcPath string, launch bool) error

func (RebuildBuildProcess) ShouldRun

func (r RebuildBuildProcess) ShouldRun(workingDir string, metadata map[string]interface{}, npmrcPath string) (bool, string, error)

type SBOMGenerator

type SBOMGenerator interface {
	Generate(dir string) (sbom.SBOM, error)
}

type Summer

type Summer interface {
	Sum(paths ...string) (string, error)
}

type SymlinkResolver

type SymlinkResolver interface {
	ParseLockfile(lockfilePath string) (Lockfile, error)
	Copy(lockfilePath, sourceLayerPath, targetLayerPath string) error
	Resolve(lockfilePath, layerPath string) error
}

type Symlinker

type Symlinker interface {
	WithPath(path string) Symlinker
	Link(source, target string) error
}

type VersionParser

type VersionParser interface {
	ParseVersion(path string) (version string, err error)
}