Upgrading

Follow the instructions for upgrading a Laravel application, while bearing the following in mind...

7.x to 8.x (12 Jul 2022)

This update is for compatibility with alberon/webpack 2.0.

6.x to 7.x (16 Feb 2022)

This update is for compatibility with Laravel 9. It includes updates to:

The changes required are:

  • When prompted by the upgrade script, remove the vue-meta JavaScript package.

  • Update all files from the template as normal.

  • Replace Nexus::shareOnce() with Nexus::config(), and change any Vue code that uses them from $page.props.<name> to $config.<name> (it's no longer possible to merge props, plus this makes it clearer). (Example here)

  • If LayoutMain.vue is being overriden, update it to match the package - add HasPageTitle and Head, and remove the head() method.

    • If there are any custom layouts, do the same.

  • In the tests, replace assertComponent(), assertProp(), assertPropCount() and assertPropExists() (or direct calls to inertiaComponent() and inertiaProps()) with the official test helpers.

  • Replace any calls to Redirect::hard() with Inertia::location().

  • If any components implement a custom head() method or object for Vue Meta, replace it with the new Inertia.js <Head> component.

These changes are optional (but recommended for consistency / forwards compatibility):

  • Use the new <Link> component instead of <InertiaLink>. You will need to import it, as it is not globally available. (The global registration of <InertiaLink> will be removed in a future version of Nexus.)

  • Replace calls to Inertia::render() with the global helper function inertia(). (Both are supported, but this is shorter and consistent with view().)

  • If any forms have uploads, you no longer need to manually create a FormData object

Package updates required:

  • alberon/nexus-generator: 2.0+ (optional)
  • alberon/nexus-users: 6.0+

Other things to be aware of:

  • Inertia now defines $props.errors for us, but it only includes the first validation error message (as a string instead of an array). This is unlikely to be a problem in practice.

Updating Packages

If you are working on any of the Nexus packages, make the same changes as listed above.

You may also need to register the Vue namespace in the tests if you use the component() helper.

5.x to 6.x (8 Oct 2021)

Chart.js was upgraded from v2 to v3 - see the Migration Guide if the project is using it.

4.x to 5.x (18 Sep 2021)

This release adds xxl, xxxl and xxxxl breakpoints and modal sizes.

The xl modal width was reverted from 97vw to the Bootstrap default of 1140px. Any existing xl size modals should be replaced with fluid size (up to 2000px), unless a smaller size works better.

4.0.x to 4.0.3+ (17 Nov 2020)

This is a bugfix release but it requires the following changes to the application:

  • Add \Alberon\Nexus\Http\Middleware\HandleInertiaRequests::class to app/Http/Kernel.php.

  • Remove the Inertia::version() section from app/Providers/InertiaServiceProvider.php (not strictly necessary, but it's no longer needed).

3.x to 4.x (12 Nov 2020)

This release splits the main entrypoint into nexus and frontend (if using Nexus CMS), and moves more of the code from the template into the package (taking advantage of component overriding to allow customisations).

The changes required are:

  • Update webpack.config.js from the template.

  • Update the resources/css/ and resources/js/ folders to match the template. Move any customisations to overrides in resources/nexus/ (see here).

  • Move resources/Shared/LayoutSidebar.vue to resources/nexus/vue/LayoutSidebar.vue.

  • Either move LayoutMain, LayoutNavbar and LayoutNavbarLogo to resources/nexus/vue/ as well (if they have been customised), or just delete them (if they haven't).

  • If it wasn't deleted, check resources/nexus/vue/LayoutNavbarLogo.vue against the default - specifically, the colour of the spinner was changed from text-warning class to a custom class with color: $yellow, and the link was changed from / to $route('nexus.home').

  • Search for @/vue/Shared/Layout in resources/ - replace with @alberon/nexus/vue/Layout.

  • Search for <CardTable in resources/ - replace any v-model="..." props with :rows="..." (because v-model now maps to selected-ids to support bulk actions).

  • Move resources/views/layouts/_head.blade.php (the Sentry code) to resources/nexus/views/layouts/head/_before_scripts.blade.php. (Note: If you are going to use Nexus CMS, the new template includes a replacement resources/views/layouts/_head.blade.php that is for the frontend, not for Nexus.)

  • Delete resources/views/errors/ (or move to resources/nexus/views/errors/ if they have been customised).

  • Delete resources/vue/Errors/ (or move to resources/nexus/vue/Errors/ to override the default).

  • Update the App\Exceptions\Handler class from the template - it should now extend Alberon\Nexus\Exceptions\Handler instead of Illuminate\Foundation\Exceptions\Handler, and some code has been moved into that parent class.

  • Delete resources/vue/Dashboard/PagePlaceholder.vue (or move it to resources/nexus/vue/Home/PagePlaceholder.vue to override the default).

  • In resources/nexus/vue/LayoutSidebar.vue, change dashboard to nexus.home in the active and href attributes, and remove v-if="$hasRoute('dashboard')" (comment out the link if there is no dashboard).

  • In routes/web.php, change name('dashboard') to name('nexus.home'), and remove the dashboard.placeholder line completely (whether it's commented out or not).

  • If there are still any references to $date() in Vue (which was deprecated in Nexus 1), replace them with the <FormatDateTime> component (or use the date-fns format() function directly).

Package updates required:

  • alberon/nexus-demo: 4.0+
  • alberon/nexus-users: 4.0+

Other changes to be aware of:

  • .text-warning was changed from yellow to orange to make it more readable. If you've used it on a dark background, switch to a custom class with color: $yellow (or similar).

  • Coloured table rows (.table-danger, etc.) are now lighter to make them more readable.

  • Inertia.js was updated - it includes some deprecations which may be displayed in the console.

  • Added vue-unique-id ($uid and $id()) for generating unique HTML IDs.

Updating Packages

If you are working on any of the Nexus packages:

  • All routes should be wrapped in Route::prefix(config('nexus.prefix')) (example).

  • Replace @/vue/Shared/LayoutMain with @alberon/nexus/vue/LayoutMain.

  • Replace @/css/shared/common with @alberon/nexus/css/common.

  • Replace DaveJamesMiller\Breadcrumbs\BreadcrumbsGenerator with Diglactic\Breadcrumbs\Generator. (More details)

  • Use vue-unique-id ($uid and $id()) for generating unique HTML IDs.

2.x to 3.x (2 Nov 2020)

This release adds support for overriding Nexus functionality in an application, particularly for the CMS & Users packages.

  • The User model moved from App\Models\User to App\NexusUsers\Models\User (because all overrides will be namespaced). You will need to update any references to it.

  • App\Models\Permission and App\Models\Role are no longer required. If they do need to be overridden, they should be moved to App\NexusUsers\Models\ like the User model (see the article above).

  • The prefix for JS/CSS imports changed from alberon-nexus/ to @alberon/nexus/ (consistent with npm namespaces). You will need to search/replace in resources/ (CSS, JS, Vue files).

  • The prefix for namespaced Inertia pages changed from alberon-nexus:: to just nexus:: (for consistency with other packages like breadcrumbs). You will need to search and replace in resources/views/.

Package updates required:

  • alberon/nexus-demo: 3.0.1+
  • alberon/nexus-users: 3.0+

Optional but recommended:

  • Change any can props to userCan for consistency / clarity.

  • In sections, change section.can to section_userCan (use _ instead of nesting for namespacing, to allow partial reloads).

  • In packages, change alberonNexusDemo.can to nexusDemo_userCan (remove the alberon prefix for simplicity, and ).

Updating Packages

If you are working on any of the Nexus packages you also need to be aware of the following:

  • Imports should now always use the full '@alberon/nexus/vue/Example.vue' syntax rather than relative paths like './Example.vue' (to allow them to be overridden).

  • Dynamic components were changed a bit to be consistent with component overriding.

1.x to 2.x (9 Oct 2020)

This update is for compatibility with Laravel 8 and Inertia-Vue 0.3.0.

In resources/vue, you will need to:

  • Search and replace $page. with $page.props. (details)
  • Recommended: Search and replace $page.props.props with $page.props to make sure you didn't change anything twice
  • Recommended: Search and replace $inertia.page with $page

Package updates required:

  • alberon/nexus-demo: 2.0+
  • alberon/nexus-users: 2.0+

FYI: I also removed a number of "Example" files from the template repo. Going forward, the Nexus Demo Application will contain the examples, with additional documentation on the Knowledge Base as needed.

0.x to 1.x (14 Aug 2020)

This is when we started moving functionality from the Template Sites repo into individual packages, including Nexus.

The few sites that were using it have been upgraded already, so I won't write detailed instructions here, but you can have a look at this revision of the Laravel upgrade instructions to see what changed. (Note: Some of the changes were Nexus-specific, while others affect all Laravel applications.)