Vue-soppy NPM | npm.io

vue-soppy

What and Why?

Check out this article on Medium to get a better understanding why vue-soppy exists.

How to setup

NOTE: This setup assumes you're using a vue-cli project with vue-router and vuex.

$ vue create my-project && cd my-project/
$ npm install vue-soppy

src/router/routes.json - Ideally, this file is auto-generated by some external script or command (check out laravel-soppy for the Laravel setup for vue-soppy)

[
  {
    "name": "app.welcome",
    "path": "/",
  }
]

NOTE: It's recommended to set up a file dedicated to the soppy instance. We put it in src/vendor/soppy.js but feel free to put it where you like. Just remember to change the references accordingly in the code snippets below.

src/vendor/soppy.js

import Soppy from 'vue-soppy';
import routes from '@/router/routes.json';

const soppy = new Soppy(routes, {
  enableSoppyLoadbarComponent: true,
});

export default soppy;
export const soppyRoutes = soppy.soppyRoutes;
export const soppyRouter = soppy.soppyRouter;
export const soppyActions = soppy.soppyActions;
export const soppyMutations = soppy.soppyMutations;
export const soppyState = soppy.soppyState;
export const soppyModules = soppy.soppyModules;

src/main.js

import Soppy from '@/vendor/soppy';
Vue.use(Soppy);

NOTE: We're importing from our dedicated vendor soppy instance and not the vue-soppy package. This is the same in the setup files below.

public/index.html (optional)

<script>
  window.SoppyState = <% if (NODE_ENV === 'production') { %>@json(array_merge($data, []))<% } else { %>{}<% } %>;
</script>

You can replace @json(array_merge($data, [])) with whatever your framework can inject data with if you're not using laravel-soppy

src/store/index.js

import Vue from 'vue';
import Vuex from 'vuex';
import { soppyState, soppyMutations, soppyActions, soppyModules } from '@/vendor/soppy';


Vue.use(Vuex);

export default new Vuex.Store({
  state: soppyState({
    // Your custom root state
  }),

  getters: {
    // Your custom root getters
  },

  actions: soppyActions({
    // Your custom root actions
  }),

  mutations: soppyMutations({
    // Your custom root mutations
  }),

  modules: soppyModules({
    // Your custom modules
  }),
});

NOTES: The second and third argument for soppyActions can optionally be setSoppyStateCallback and setSoppyPreloadStateCallback respectively.

src/router/index.js

import Vue from 'vue';
import VueRouter from 'vue-router';
import { soppyRoutes, soppyRouter } from '@/vendor/soppy';

Vue.use(VueRouter);

const routes = soppyRoutes([
  {
    name: 'app.custom.modal',
    path: '{app.custom}/modal',
    meta: {
      soppy: {
        get path() {
          return window.location.pathname.replace('/modal', '');
        },
      }
    },
    components: {
      default: () => import('@/views/Promo.vue'),
      modal: () => import(/* webpackChunkName: "custom-modal-view" */ '@/views/custom/Modal'),
    },
  },
  {
    name: 'app.notFound',
    path: '*',
    components: {
      default: () => import(/* webpackChunkName: "not-found-view" */ '@/views/NotFound'),
    },
  },
]);

const router = new VueRouter({
  // mode: 'history',
  // base: process.env.BASE_URL,
  routes,
});

export default soppyRouter(router);

NOTES:

Pass in any vue-specifc routes or route overrides to the soppyRoutes method. These will be merged with the routes from your routes.json that you passed in to the Soppy class in @/vendor/soppy.js.
Pass in an object of any overrides you want on every route as the second argument to soppyRoutes
Each route's components property is generated dynamically from the route's name from the routes.json. By default, for example, the component property for app.welcome will be { default: () => import('@/views/Welcome.vue') }; or for nested routes like app.user.settings, { default: () => import('@/views/user/Settings.vue') }. To change the naming convention used here, override the component or components property as explained above OR pass in your own naming function as the third argument to soppyRoutes. NOTE: All component paths will be prepended with '@/' after your naming function to bypass some dynamic import limitations.
The first route we're passing in the above example, app.custom.modal is how you might implement a child route of sorts.
- The path includes curly brackets around another route's name: {app.custom}. This will be replaced by the actually path from app.custom found in routes.json
- get path() in a route's meta.soppy object will override the path that will be called to fetch data. In the example case above, we want the same data that fetched in the parent route.
- The SoppyApp component has two router views: 1 is default and the other is named: modal. This way you can show multiple views (e.g. a parent and a child) at the same route.

Your app needs to be wrapped in the <soppy-app> component like this:

src/App.vue

<template>
  <soppy-app
    id="app"
    :view-not-found="notFound"
    :view-server-error="serverError"
    :view-attrs="{ class: 'mt-7 leading-6' }"
  >
    <!-- optionally include the soppy-loadbar component -->
    <soppy-loadbar></soppy-loadbar>

    Header / Anything before router-view
    
    <template v-slot:after>
      Footer / Anything after router-view
    </template>
  </soppy-app>
</template>

<script>
export default {
  name: 'App',

  data() {
    return {
      notFound: () => import(/* webpackChunkName: "not-found-view" */ '@/views/NotFound'),
      serverError: () =>
        import(/* webpackChunkName: "server-error-view" */ '@/views/ServerError'),
    }
  }
}
</script>

NOTES:

If you want to show a specific view when a soppy request returns a 401, 404, or 500, you can add the :view-unauthorized, :view-not-found, :view-server-error attributes respectively.
:view-attrs will be bound to the default component slot which is <router-view> by default
View the SoppyApp component for more details
Use <soppy-link> to take advantage of extra functionality like preloading data on link hover. Use it like <router-link> and check out the component file for more details.
<soppy-loadbar> is a tailwindcss-styled component showing the load progress of the soppy page requests. Check out the component file for more details.