Nova Nexmo Laravel Package

Getting Started

The only substantive signal in this release is packaging: v1.0.1 commits the compiled dist/ folder and removes it from .gitignore. That tells you the package has a frontend build step (Vite/webpack/rollup + npm run build) producing consumable assets, and that upstream now intends those artifacts to ship with the release rather than be generated by the consumer.

First steps:

1. Install and confirm dist/ landed. Because dist/ is the thing that changed, verify it actually reaches you:

   composer require <vendor>/<package>:^1.0.1
   ls -la vendor/<vendor>/<package>/dist
   

   If that directory is empty or missing, you are not on the new artifact — check your lock file, your VCS tag, and the package's .gitattributes (see Gotchas).
2. Read composer.json before anything else — the extra.laravel.providers, extra.laravel.aliases, and extra.laravel.assets/publish tags are what tell you how the compiled assets are meant to be surfaced.
3. Publish, don't reference. If the package exposes publish tags, run php artisan vendor:publish --provider="Vendor\Package\ServiceProvider" and inspect what tags appear.
4. First use case: a fresh install on a machine with no Node toolchain. Prior to v1.0.1 you likely had to cd vendor/<vendor>/<package> && npm ci && npm run build. The immediate win is that a plain composer install in CI, or a composer require on a build box, now yields working assets with zero JS tooling.

Implementation Patterns

Pattern A — consume from vendor/ at runtime. Point @vite/asset() at the published path and require consumers to re-copy on upgrade:

<link rel="stylesheet" href="{{ asset('vendor/package/package.css') }}">

Copy assets on every deploy (vendor:publish --tag=package-assets --force) so the served files always match the PHP code.

Pattern B — publish once, own the copy. Publish into resources/ or public/vendor/ and commit it to your app repo. You control cache-busting and CDN paths, but you own the diff on every upstream bump. Pair this with a CI check that flags when the published files drift from vendor/.../dist.

Pattern C — rebuild locally (escape hatch). If you are patching the package, or you install from a branch/symlinked path repo, there is no shipped dist/ to fall back on. Document the fallback in your README:

cd vendor/<vendor>/<package>
npm ci && npm run build

Deploy pipeline tip. Since v1.0.1 vendors the build output, your production image no longer needs a Node stage for this dependency. Drop npm ci && npm run build for it from the Dockerfile and keep Node only for your own app assets — it shrinks build time and removes a whole class of "build failed because of a transitive devDependency" failures.

Version pinning. Treat dist/ as opaque build output and pin the package in composer.lock. Pinning is more valuable now: a minor release can silently change compiled JS/CSS in ways that never appear in the PHP diff, so review the assets as well as the classes when upgrading.

Gotchas and Tips

.gitattributes can silently strip the fix. The classic trap: dist is committed and un-gitignored, but export-ignore in .gitattributes (or archive.exclude in composer.json) removes it from the dist tarball. Git users get the assets; composer-from-Packagist users don't. Verify by installing from the tagged archive, not from a path/vcs repo:

composer require <vendor>/<package> --prefer-dist

This is the single highest-probability regression for a release whose entire content is "we now ship build output."

Symlinked path repositories bypass dist entirely. If you develop against the package via "repositories": [{"type": "path", "url": "../package"}], you get the working tree. If dist/ is gitignored in your fork or in a branch cut before the merge, you get nothing. This is a common cause of "works in the app, breaks in CI."

Stale dist after upgrade. composer update replaces files in place; published copies and CDN edges do not follow. After bumping the package:

php artisan vendor:publish --tag=package-assets --force
php artisan view:clear && php artisan config:clear

Then bust your asset cache. A browser-cached CSS file paired with new PHP is the most confusing failure mode here — the markup changes but the styles don't.

Never edit vendor/.../dist. It is overwritten on the next composer install. Override by publishing and editing the published copy, or by extending the component in your app.

Committed build artifacts mean diff noise and merge conflicts. If you ever contribute upstream, every dist/ commit is a large binary-ish blob. Ask for the build to be reproducible (npm ci, pinned lockfile, no timestamps/banner dates) and for a CI job that runs the build and fails on git diff --exit-code dist/. Otherwise you are trusting that the committed dist/ matches src/ — nothing enforces it.

.gitignore removal is a one-way door. Once dist/ is tracked, forgetting to rebuild before a release tag ships stale assets. Add a release checklist item, or a composer script / CI step that runs the build and verifies cleanliness ahead of tagging.

Extension points. Look for a config file exposing asset paths or CDN base URLs, and for publish tags that let you split "config" from "assets." If the package resolves asset URLs via config('package.asset_url'), setting that to your CDN is cleaner than rewriting Blade views — but only if the published dist filenames are stable, which they may not be if hashing is enabled. Check the manifest before leaning on this.

Assessment confidence note. This release is a packaging change only — no new features, no deprecations, no API surface change. If dist/ in fact never makes it into the distributed archive, v1.0.1 is a no-op for Packagist consumers and you should stay on your existing local-build workflow until a follow-up fixes .gitattributes.