Frontend Tools Laravel Package

Getting Started

This release (pressbooks/frontend-tools 1.0.0) is a frontend build/lint tooling package, not a PHP/Composer library. Before writing any application code, confirm that assumption — the only artifact in the release notes is a commit-range link, so the authoritative sources are, in order:

1. README.md in the tagged tree — usage and exported configs.
2. package.json — the exports map, peerDependencies, engines.node, and shipped binaries.
3. git log v0.9..v1.0.0 or git diff <previous-tag>..1.0.0 — the changelog link points at commits, not curated notes, so diff the tags locally to see what actually changed.

Install it as a dev dependency in the app or theme that owns the asset pipeline:

npm install --save-dev pressbooks/[email protected]

Do not add it to composer.json, and do not expect a service provider or published config — it is consumed at build time by Node, sitting upstream of whatever emits public/build.

First use case: replace a hand-rolled webpack.mix.js / vite.config.js / .eslintrc set with the shared presets this package ships, then verify the resolved config and a clean npm run build before touching lint rules. Because 1.0.0 is the first stable major, treat adoption as "evaluate the resolved defaults," not "drop in and ship."

Implementation Patterns

Extend, don't fork. Consume the exported configs and layer local overrides on top; a copied config drifts on the next release and you lose the upgrade path entirely.

// vite.config.js
import { defineConfig } from 'vite';
import base from 'pressbooks/frontend-tools/vite'; // verify exact export path in package.json

export default defineConfig({
  ...base,
  build: { outDir: 'public/build' },
});

Pin and lock. Use an exact version ("1.0.0", not "^1.0.0") and commit package-lock.json. Build tooling changing underneath you is a silent CI failure, not a loud one.

Separate the lint job from the build job. Run the package's lint/format binaries as their own CI step so a style failure doesn't mask a compile failure, and so lint can run on a cheaper runner without a full Node build.

Keep the PHP and Node toolchains in distinct directories. If the Laravel app ships a Pressbooks theme or plugin alongside it, scope the package to that subtree's package.json rather than hoisting it to the repo root — it prevents the tooling's ESLint/Browserslist defaults from leaking into unrelated frontend code.

Treat version bumps as config diffs. On every upgrade, dump the resolved config and diff it against the previous output. That is the only reliable way to see what a tooling major actually changed when release notes are absent.

Gotchas and Tips

• 1.0.0 does not mean "same as 0.x, now stable." A first stable major frequently freezes defaults that were previously in flux: lint rule sets, Browserslist targets, output filenames, or module format. Diff resolved configs (npx eslint --print-config, vite build --debug, or a small script that imports and logs the exported object) before and after.
• Peer dependency duplication is the most likely failure mode. Build tooling packages usually declare webpack/vite/eslint as peers. A mismatched or duplicated copy produces confusing "two versions of X" errors. Diagnose with npm ls <peer> and npm dedupe rather than guessing.
• Check engines.node first. If the package bumped its Node floor, CI images and local .nvmrc will both need updating; the symptom is usually a syntax error in the package's own source, which reads like your bug but isn't.
• ESLint flat-config migration is a common breaking change in a 1.0. If the package moved from .eslintrc to eslint.config.js, existing overrides in your repo will be silently ignored rather than erroring.
• Absent release notes are a real risk signal. With only a commit-range link, verify by reading the commits that touch package.json, exported config files, and any renamed paths — path renames in an exports map break imports with an unhelpful ERR_PACKAGE_PATH_NOT_EXPORTED.
• Don't let build artifacts drift into the PHP deploy. Confirm public/build (or equivalent) is gitignored and rebuilt in CI; a tooling bump that changes hashed filenames will otherwise leave stale manifests and 404s on assets.
• Extension points to reach for before patching: a documented overrides/options argument on the exported factories, browserslist in your own package.json (usually wins over a preset default), and standard env vars like NODE_ENV/BROWSERSLIST_ENV. If none of those cover your case, check whether the package ships granular entry points (lint-only, build-only) instead of forking the repo.