Slim Starter Laravel Package

Getting Started

Treat 2.0.0 as a tooling upgrade, not a runtime dependency bump — nothing ships to production from this package itself, but it changes how your front-end assets are built and tested.

Minimal steps:

1. npm install --save-dev <package>@^2.0.0 (or yarn add -D), then re-run your asset pipeline once before touching any code — most upgrade failures surface here, not in your components.
2. Install the peers the release assumes: vue, vue-template-compiler (must match vue exactly), vue-loader, babel-core/babel-preset-env, jest, @vue/test-utils, and vue-jest.
3. Open your build config file first (webpack.mix.js, gulpfile.js, or the package's published config). This is where the 2.0.0 breaking change lands: the single-file setting is now a list of entry points. Migrate entry: 'app.js' → entry: ['app.js', 'admin.js'] (or the equivalent array/object form) before running a build.
4. Add "test": "jest" to package.json scripts and confirm npm run test passes on an empty suite.

First use case: take one existing Blade page, extract its inline JS into a .vue single file component, compile it through the new pipeline, and mount it with new Vue({ el: '#app' }). Then write the trivial shallowMount test for that component immediately — the value of the release is that component and test are introduced together, so prove the loop works before migrating the other twenty components.

Implementation Patterns

One entry point per Blade layout. The multiple-file compilation support is the headline feature; use it to stop shipping an admin bundle to public pages. Define entries as a map so output names stay stable and predictable:

// webpack config block
entry: {
  'public/app': './resources/assets/js/app.js',
  'admin/app': './resources/assets/js/admin.js',
}

Each entry gets its own dependency graph, so a heavy admin-only library never lands in the public bundle. Pair this with mix.version() (or your hashing plugin) and reference the manifest from Blade rather than hard-coding paths.

Register components per entry, not globally. With multiple bundles, a global Vue.component() call in a shared file silently bloats every page. Keep a small shared bootstrap.js for the Vue instance and plugins, and let each entry import only the components that page needs.

Colocate tests with components. A pattern that ages well:

resources/assets/js/components/
  UserPicker.vue
  __tests__/UserPicker.spec.js

Use shallowMount for unit tests and reserve mount for components whose behaviour genuinely depends on child rendering. Stub HTTP with mocks: { $http: ... } rather than hitting a real endpoint — Jest runs in jsdom, there is no Laravel app behind it.

One Babel config for build and test. The release adds Babel transpilation; the trap is ending up with two configs. Have babel-jest consume the same .babelrc/babel.config.js as the Webpack build, and set targets: { node: 'current' } under env.test so Jest doesn't down-compile to ES5 needlessly and blow up transform time.

Scripts as the daily workflow. Standardise on npm run dev (fast, unminified, source maps), npm run watch during development, npm run production (minified, hashed) in deploy, npm run test in CI. Anything a developer has to remember beyond these four commands is a documentation bug.

CI integration. Run npm run test and npm run production as separate steps so a failing test doesn't mask a failing build. Cache node_modules keyed on package-lock.json; the Jest + Babel toolchain makes cold installs slow enough to notice.

Gotchas and Tips

• vue and vue-template-compiler version skew is the single most common failure with SFC pipelines. They must be the exact same version — not just compatible semver. Pin both or add a postinstall check.
• The 2.0.0 config change is breaking in practice even if it looks additive. Audit every project's build config for the old single-file form; a string where an array is expected often fails silently (one entry built, others ignored) rather than throwing. Verify by checking the emitted asset count after the first build.
• Path resolution in multi-entry configs is usually relative to the project root, not the package or the config file. Symptom: one entry compiles, the others produce empty or missing bundles with no error. Log the resolved entry paths once when debugging.
• Runtime-only vs compiler-included Vue. If you mount to a DOM element with an in-DOM template, you need the full build (vue/dist/vue.esm.js via resolve.alias); otherwise you get the "You are using the runtime-only build" warning and a blank page. SFCs avoid this entirely — which is a reason to migrate templates into .vue files rather than keep them in Blade.
• Jest choking on CSS or asset imports. SFCs importing styles or images need moduleNameMapper stubs in the Jest config. Add them the first time it bites, not per-test.
• <style> extraction. Scoped styles and CSS extraction need vue-loader plus an extract plugin wired for the SFC block. In dev, prefer style injection over extraction so hot reload keeps working.
• Watch mode with multiple entries. Expect only the changed entry's chain to recompile; if all entries rebuild every save, your entries share a common import that's being treated as a barrel — split it.
• Debugging build failures: enable --display-error-details (or the equivalent verbose flag) and keep devtool: '#eval-source-map' in dev only. Stack traces from Babel-transpiled SFCs are unreadable without source maps, and production source maps leak source.
• Extension points: the published config is designed to be merged, not edited in node_modules. Use the package's config-merge hook / mix.override for custom loader rules, and keep project-specific tweaks in one clearly-commented block so the next upgrade diff is small.
• Third-party SFCs in node_modules are often untranspiled ES2015+. If Jest or the build fails on a vendor .vue file, add it to the transpile allowlist rather than forking the package.