Webniu Laravel Package

Getting Started

v1.3.0 moves the package to a base + sub-application micro-frontend architecture. The most important consequence for a Laravel developer is that the main framework is compiled once, and each functional module (sub-app) is now built, packaged, installed and uninstalled independently. That changes both your local workflow and your deployment pipeline, so read this before touching code.

Minimal path to a working install:

1. composer require the package into a fresh Laravel app (Laravel 9/10/11 depending on your constraint), then run the installer/publish command to emit config, migrations and the base frontend scaffold.
2. Run migrations and seed the base permissions/menus.
3. Compile the base frontend once (npm install && npm run build in the base app). You should not need to rebuild it again when adding or removing modules — that is the headline feature of 1.3.0.
4. Install a sub-application (either the bundled examples or one you scaffold) and confirm it appears in the admin shell without a base rebuild.
5. Log in, verify the menu entry and permissions for that sub-app.

Where to look first:

• The package config file (config/<package>.php or equivalent) for the module/sub-app registry, install paths and asset disk.
• The sub-application directory layout: each sub-app typically carries its own composer.json, frontend package.json, routes, migrations, service provider and a manifest describing its menu/permissions.
• The base frontend host that loads sub-apps — this is where the micro-frontend contract (entry URL, shared dependency map) lives. This is the file that determines whether a sub-app loads at all.

First use case: scaffold one thin sub-app (a single CRUD screen), install it, and uninstall it. Doing this once end-to-end teaches you the lifecycle before you inherit someone else's module.

Implementation Patterns

Treat a sub-app as a deployable unit, not a folder. Each sub-app should own its routes, migrations, permissions, menu entries and frontend bundle. Registration belongs in the sub-app's service provider, loaded through the base registry — avoid adding require lines to the base app's providers by hand, since that defeats the install/uninstall model and will drift.

Install/uninstall lifecycle. Wire install and uninstall into artisan commands or the package's own install mechanism, and make them idempotent:

• Install: run migrations, seed permissions/menus, publish the built frontend assets to the public/asset disk, register the entry in the module registry, clear caches.
• Uninstall: remove the registry entry and assets, and decide deliberately what happens to data (drop tables vs. keep for reinstall). Default to keep and require an explicit --purge flag — silent data loss on uninstall is the most common complaint with this style of architecture.

Independent frontend development. Use the sub-app's own dev server with a proxy/HMR configuration pointed at the base host. Keep shared dependencies (Vue/React, UI library, state manager) declared as externals or in a shared import map so the sub-app does not ship a second copy of the framework. A duplicated runtime is the fastest way to get "two instances of the store" bugs.

Contract versioning. The base shell exposes a contract (mount function signature, event bus, shared services, route helpers). Pin the sub-app against a base contract version and record it in the sub-app manifest. On v1.3.0, base and sub-apps are now separately versioned, so this pin is your only protection against a sub-app built for an older shell.

Integration points in Laravel. Menu/route/permission registration should flow through the registry so a sub-app can be added without editing base files. For anything shared — auth context, current user, permission checks — expose it from the base shell rather than re-fetching inside the sub-app; duplicated auth calls are a recurring source of flickering UIs and 401s on cold load.

Deployment. Build sub-apps in their own CI jobs and publish artifacts to wherever the base shell fetches them from. Because the base no longer recompiles, deployment becomes: upload sub-app bundle → run install/migration step → flush caches. Keep the previous sub-app bundle addressable so a rollback is an asset swap, not a full redeploy.

Upgrading the base. With decoupled builds you can upgrade the base shell without rebuilding every sub-app — but only if the contract is stable. Test the oldest sub-app you still support against the new base before rolling out.

Gotchas and Tips

• No base rebuild means cache invalidation is now your job. After installing or uninstalling a sub-app, clear config, route, view and application caches, and bust any asset-manifest/version cache. "I installed it and nothing changed" is almost always a stale cache or a stale manifest.json being served.
• Asset manifest mismatch. The base shell resolves sub-app entry files through a manifest. If the manifest is written by the build but the assets land somewhere else, you get a blank screen with a 404 buried in the network tab. Verify the public path in the manifest matches the disk you publish to.
• The "small fix" is unspecified. v1.3.0 item 4 says only that a minor issue was fixed. Before upgrading, check the commit log/diff between tags and scan for changes in the frontend contract files — an unlabelled fix in the shell can be a silent breaking change for existing sub-apps.
• Uninstall must be reversible in practice. Test reinstall over existing data. Migrations that assume a clean database, and permission seeds that create duplicates, are common; use updateOrCreate/firstOrCreate in seeders and guard migrations.
• Duplicated dependencies. If a sub-app bundle contains its own copy of the base framework, you will see doubled payloads, broken shared state, and event bus listeners that never fire. Check bundle size and inspect the built output for the framework chunk.
• Route and permission name collisions across independently developed sub-apps are easy to introduce and painful to debug. Enforce a prefix convention (e.g. subapp.resource.action) in your module scaffolding.
• Upgrade order matters. Upgrade the base first, then sub-apps. Downgrading a sub-app after a base upgrade is generally safe only if the contract version was bumped properly — verify rather than assume.
• Extension points worth knowing: the sub-app registry (for programmatic install/uninstall), the shared-dependency map in the shell, the menu/permission seeders, and any middleware that injects the current sub-app context. Those four are where most customisation and most breakage happens.
• Debugging a sub-app that won't load: confirm the registry entry exists, confirm the entry asset returns 200, confirm the contract version matches, then check the browser console for shared-dependency resolution errors. That order resolves nearly every case.