Paper Laravel Package

Getting Started

This package is a one-shot Laravel frontend preset, not a runtime library. Running it replaces Laravel's default Blade/auth/asset scaffolding with Creative Tim's Paper Dashboard — a Bootstrap 4 + jQuery admin theme with a sidebar layout, cards, tables, and Chartist charts. Your day-to-day leverage comes from the generated resources/views, resources/sass, resources/js, and build config, not from calling package APIs.

What v1.0.5 changed: the only release note is "Update to Laravel 10.x". That is a support-matrix bump, not a feature change — no new commands, no new config, no new stubs documented. Practically it means the package's composer.json constraints now allow Laravel 10, so composer require will resolve on a Laravel 10 app where it previously failed. Laravel 11 and 12 are still not claimed by this release — do not assume they work; check composer.json and the README before installing on those versions. Note the tension: Laravel 10 defaults to Vite, while this preset is still a webpack-mix/Bootstrap-4-era scaffold, so "supports Laravel 10" does not mean "drops into a stock Laravel 10 app and npm run dev just works" (see Gotchas).

Install and scaffold

# 1. Commit or stash first — the preset overwrites files
composer require laravel-frontend-presets/paper:^1.0.5 --dev

# 2. Run the preset. Laravel 7+ uses the laravel/ui command form:
php artisan ui paper
# Older Laravel (≤6) used: php artisan preset paper
# Check the README for your Laravel version before assuming the command name.

# 3. Auth routes/controllers are NOT installed by a frontend preset
composer require laravel/ui --dev
php artisan ui:auth        # creates routes, controllers, and default auth views
# then re-run the paper preset if you want its auth views to win:
php artisan ui paper

# 4. Build assets
npm install
npm run dev

Verify the exact command and the supported Laravel constraint in the package README and composer.json. After v1.0.5 that ceiling is Laravel 10; on Laravel 11/12 expect to fork or pin laravel/ui and patch constraints yourself.

Where to look first

• resources/views/layouts/ — the main Paper Dashboard shell (.wrapper, sidebar, navbar, .main-panel).
• resources/views/auth/ — login/register/password views styled for Paper.
• resources/sass/app.scss and any imported Paper partials.
• resources/js/bootstrap.js / app.js — jQuery, Bootstrap 4, Perfect Scrollbar, Chartist wiring.
• webpack.mix.js — the preset's asset pipeline assumptions. On a fresh Laravel 10 install this file will not exist until the preset writes it; confirm it did.
• vendor/laravel-frontend-presets/paper/src/ — the preset class and stubs/ directory; diff these against what was written to know exactly what changed. After the 1.0.5 bump, re-diff to see whether the Laravel 10 support touched stub files or only composer.json.

First use case

Scaffold an authenticated admin area: install the preset, generate auth routes with laravel/ui, wrap Route::get('/home', ...) in auth middleware, extend layouts.app in your page, and render a dashboard card grid. Confirm npm run dev produces a working sidebar and that /login renders the Paper-styled form.

Implementation Patterns

Treat the preset as a generator, then own the output. After scaffolding, the generated files are ordinary application code. You can remove laravel-frontend-presets/paper from require-dev once you're satisfied (or keep it to bootstrap future projects). Day-to-day work happens in your Blade/SCSS/JS, not in the package.

Respect the layout anatomy. Paper Dashboard's JS and CSS expect a specific nesting:

<div class="wrapper">
  @include('layouts.sidebar')
  <div class="main-panel">
    @include('layouts.navbar')
    <div class="content">
      <div class="container-fluid">
        @yield('content')
      </div>
    </div>
  </div>
</div>

Pages extend the layout and fill @section('content'). Dropping a page into .content without .container-fluid/.row/.col-* usually breaks spacing and card alignment.

Reuse partials for CRUD screens. Extract sidebar, navbar, and footer into partials. Drive active nav state with request()->routeIs('users.*'). For index pages, use Paper's .card + .table markup; for show/edit, reuse the same shell so every page gets the sidebar behavior for free.

Auth integration. Let laravel/ui generate controllers and routes; let the preset own only the views. If you re-run the preset after customizing auth views, you'll lose those changes — either don't re-run, or copy your changes into the package's stubs.

Charts and dashboard data. Chartist expects a container with a ct-chart class and initialization after the DOM is ready. Pass server data into inline scripts with @json($series) rather than hardcoding, and keep chart init in a page-specific script block or a dedicated JS module so it doesn't run on pages without a chart canvas.

Customize via an override layer, not by editing generated files in place. Add a resources/sass/_overrides.scss imported last in app.scss, override Paper's variables/classes there, and keep the generated partials close to stock so you can diff against the package stubs when upgrading or debugging.

Upgrading the package version means re-running the destructive scaffold. Because v1.0.5 is a version bump of a generator, pulling it in does not "upgrade" your app in place — you'd re-run php artisan ui paper and get the stubs rewritten. If you want the Laravel 10 constraint update without losing customizations, bump the constraint in composer.json/lockfile and skip re-running the command.

Deployment. Run npm run production (Mix) or the equivalent build step in CI, and ensure compiled assets, fonts, and images are either committed or built on deploy. Paper's theme assets often rely on relative URL resolution from SCSS; verify the emitted public/ paths rather than assuming.

Gotchas and Tips

• php artisan preset was removed in Laravel 7. Use php artisan ui paper on modern versions. If the command is missing: composer dump-autoload, php artisan config:clear, and confirm the package's service provider is discovered and its Laravel constraint matches yours.
• Laravel 10 is the new stated ceiling — 11/12 remain unsupported. v1.0.5 only claims Laravel 10.x. Laravel 11 removed/changed things laravel/ui and older service providers rely on (PHP 8.2 floor, slimmer skeleton), so attempting 11/12 means editing composer.json constraints and expecting breakage. Pin laravel/framework to a 10.x line if you adopt this preset.
• The preset is destructive. It overwrites layouts/app.blade.php, home.blade.php, app.scss, app.js/bootstrap.js, and webpack.mix.js. Commit before running; never run it casually on an established app. This applies equally when "upgrading" to v1.0.5.
• Mix vs Vite. Laravel 9+ defaults to Vite, and Laravel 10 — the version v1.0.5 targets — is Vite-first, while this preset is webpack-mix/Bootstrap-4-era. Expect npm run dev to fail on a stock Laravel 10 project until you either install laravel-mix (and remove/ignore vite.config.js) or manually port the compiled assets and entry points to vite.config.js. This is still the most common integration failure, and the 1.0.5 release note does not mention addressing it — verify the emitted webpack.mix.js stub before assuming the pipeline was modernized.
• Old front-end dependency chain. Bootstrap 4, jQuery, Chartist, and Perfect Scrollbar are pinned to older versions and the 1.0.5 note says nothing about front-end upgrades. node-sass may not build on modern Node; prefer sass (dart-sass) and pin Node via .nvmrc. Run npm audit and upgrade deliberately rather than blindly.
• Auth views ≠ auth routes. The preset styles login/register but doesn't create routes or controllers. Without Auth::routes() or php artisan ui:auth, those forms 404.
• jQuery must stay global. Paper's plugin scripts expect window.jQuery/window.$. Load order in bootstrap.js matters; removing jQuery to "modernize" silently breaks dropdowns, sidebar toggles, and tooltips.
• Perfect Scrollbar needs the wrapper structure. If .wrapper lacks proper height or the sidebar markup is altered, scrolling and the mobile sidebar toggle stop working. Check the generated layout before restructuring.
• Bootstrap 4 vs 5. Don't pull Bootstrap 5 expecting compatibility — dropdown/tooltip data attributes and JS APIs changed. Keep Bootstrap 4 while using this theme.
• Fonts and images can 404. SCSS imported from node_modules resolves asset URLs relative to node_modules, not public. Verify the compiled CSS paths and copy theme assets to public/ if needed.
• Purging CSS can delete Paper classes. If you add Tailwind, PurgeCSS, or similar, safelist Paper's dynamic classes (.ct-*, .navbar-*, sidebar states) or the dashboard will render unstyled in production only.
• Debugging technique: diff your generated files against vendor/laravel-frontend-presets/paper/src/stubs/. That tells you exactly what the preset wrote and what you changed. Re-run this diff after bumping to 1.0.5 to see if any stub content shifted alongside the Laravel 10 constraint change.
• Extension point: fork the package's stubs or write your own preset class extending the package's preset if you need a house standard (e.g., your own sidebar links, extra auth fields). There is no publishable config to speak of.
• Maintenance risk: still a small, low-traffic package (50 stars, zero dependents). The 1.0.5 release shows it is alive and tracking Laravel versions, but a single-line changelog for a major-version jump is thin evidence of ongoing front-end maintenance — the Bootstrap 4/jQuery/Vite gap remains your problem. Treat it as a starting template you vendor into your repo, not a long-term dependency, and plan to fork for Vite, Bootstrap, and security upgrades.