Download the PHP package boralp/laravel-vite-apple-container without Composer

Laravel Vite Apple Container

Build Laravel Vite frontend assets inside an isolated Apple Container.

This package is designed for macOS users who use github.com/apple/container. It runs npm ci and npm run build in a hardened container with restricted filesystem access, disabled network access by default, and npm lifecycle scripts disabled by default.

The primary interface is a Laravel Artisan command:

A Composer binary wrapper is also provided:

The wrapper forwards arguments to the Artisan command.

Installation

Install via Composer:

If you need this package during production deployment builds, install it without --dev:

Laravel package discovery will register the Artisan command automatically.

Quick Start

From your Laravel project root, run the first build with network access so npm ci can download dependencies:

Or use the Composer binary wrapper:

Your compiled CSS and JavaScript assets will be written to:

By default, the project source is mounted read-only. Only public/build is writable on the host.

After dependencies have been installed once, subsequent builds can usually run without network access:

Requirements

• macOS with Apple Container installed
• Laravel 12.x or Laravel 13.x
• Laravel project with:
  • artisan
  • package.json
  • package-lock.json
• Apple Container system started:

Configuration

The package ships with a Laravel config file.

Publish it with:

This creates:

Available environment variables:

Default config:

How It Works

The command runs the Laravel frontend build inside Apple Container using a pinned Node Alpine OCI image.

Default container behavior:

The project source remains read-only in default mode even when the container runs as root. The only host path mounted writable is public/build.

In default mode, the project is copied from a read-only mount into a temporary working directory inside the container. The package keeps node_modules in a named Apple Container volume and restores it into the temporary working directory when available.

Commands

Primary command:

Composer binary wrapper:

The wrapper is equivalent to:

All flags are supported by both forms.

Running the command without flags does not start a build. Because network access is disabled by default, a no-flag run would otherwise attempt npm ci without registry access. Instead, the command exits with guidance.

Regular Usage

First run, usually with npm registry access:

Subsequent builds, using the existing isolated node_modules volume:

Install dependencies only:

Build assets only:

Allow lifecycle scripts during install:

Using the binary wrapper:

Flags

Show command help:

or:

Security Model

Default Protection

By default, the command protects against common npm supply-chain and build-time risks:

• Blocks network access unless --allow-network is passed
• Disables npm lifecycle scripts unless --allow-scripts is passed
• Prevents writes to application source files
• Allows writes only to public/build
• Keeps node_modules in an isolated container volume
• Uses a read-only container root filesystem
• Uses tmpfs for temporary writable locations
• Avoids host shell interpolation
• Applies CPU and memory limits from config

In default isolated-volume mode, the process may run as root inside the container so it can manage the private named volume used for node_modules. This does not make the project source writable; the project is still copied from a read-only mount into a temporary working directory.

Important Limitations

This tool reduces risk; it does not make arbitrary JavaScript safe.

npm run build still executes code from your package.json. A malicious build script can still affect writable locations such as public/build, consume resources within configured limits, or attempt attacks against the container runtime.

Use extra caution with:

That combination allows dependency install scripts to run with network access and should only be used for trusted projects.

Highest-Risk Mode

This mode gives the build process writable access to the whole project and should only be used for trusted codebases.

Apple Container

This project targets Apple Container, not Docker or Podman.

Check installation:

Start the container system:

Pull the Node image manually if desired:

Updating the Pinned Node Image

The command uses a pinned image digest for reproducibility.

To update it intentionally:

Review the new digest, then update either:

or the published config value in:

If you have not published the config file, update the package default in config/lvac.php.

Troubleshooting

Apple container CLI not found or not executable

Install Apple Container and make sure the container command is available:

If the binary is in a custom location:

or set it in .env:

Apple Container is installed but not running

Start the container system:

Then retry:

npm ci fails without network

This is expected on first install. Network is disabled by default.

Run:

Then build without network:

vite: not found

This usually means dependencies have not been installed into the isolated node_modules volume yet.

Run:

After that, build-only mode should work:

A package requires postinstall scripts

Some packages need lifecycle scripts.

Use:

Then build:

Only use --allow-scripts after reviewing the dependency tree.

public/build is empty

Check that Laravel Vite is configured correctly.

Typical vite.config.js:

Permission problems writing public/build

Ensure the directory is writable by your user:

Then retry:

Build needs to write outside public/build

Default mode intentionally blocks this.

For trusted projects only:

Host node_modules is required

By default, dependencies are installed into an isolated Apple Container volume, not the host project.

For trusted projects only, you can use host node_modules:

--host-node-modules requires --full-access.

How It Differs from Local npm

CI/CD

This tool is intended primarily for Apple Container on macOS. For Linux CI environments, use the project’s normal Node build pipeline unless your CI runner also supports Apple Container.

Example conventional CI build:

Threat Model Summary

Good fit:

• Trusted Laravel projects
• Reducing npm supply-chain exposure
• Preventing accidental project source writes
• Reproducible local frontend builds on macOS

Not a complete sandbox for:

• Fully untrusted repositories
• Malicious package.json build scripts
• Arbitrary npm command execution
• Secrets protection if secrets are already present in readable project files

Security

If you find a security issue, do not open a public issue. Contact the maintainer privately.