vue-just-ssr

CLI tool to spin up a Vue SSR dev environment using your own Webpack config!

This tool is designed to add a SSR dev-env to a project with Vue and Webpack already set up, and isn't a rapid prototyping tool like Vue CLI.

🙋‍♂️ Why?

🏃‍♂️ Jump start Instantly get a Vue dev environment with SSR and HMR!
🎛 Full control Pass in your own Webpack config with Vue setup, we'll do the rest!
🔥 Vue version agnostic Install your own version of Vue 2 and Webpack 4!

🚀 Install

npm i -D vue-just-ssr vue-server-renderer

Note: Assuming you already have webpack and vue installed, your vue-server-renderer version should match vue's

⚡️ Demos

Check out the demos to see how easily a Vue SSR + HMR dev environment can be setup in your repo.

🚦 Getting started

Webpack config

This module is designed for adding SSR to an existing Vue + Webpack codebase, but if you're starting a new one, make sure you have at least a bare miniumum Webpack config (eg. webpack.config.js) setup for a Vue app.

If you're interested in what this looks like, checkout the Webpack config in the demo.

Add the JustSsrPlugin to your Webpack config in the plugins array:

+ const { JustSsrPlugin } = require('vue-just-ssr');

  module.exports = {
      ...,

      plugins: [
          ...,
+         new JustSsrPlugin()
      ]
  }

npm script

You can use vue-just-ssr in your npm package.json scripts simply by referencing it as just-ssr.

  {
      ...,

      "scripts": {
+         "dev": "just-ssr --webpack-config <webpack config file>"
      },

      ...
  }

CLI

Alternatively, use it straight from your commandline via npx.

npx just-ssr --webpack-config <webpack config file>

🎨 Customization

Server address

Flag: --address, -a

Default: 127.0.0.1

Example: just-ssr -a 0.0.0.0

Use this flag to set the address for the server to bind to. If not provided, it checks process.env.HOST before falling back to 127.0.0.1 (or localhost).

The default address 127.0.0.1 is chosen for security reasons—it's a loopback address which means it is not exposed to the rest of your local area network (LAN). If you wish to expose the server externally, bind the address to all interfaces via 0.0.0.0 or a more specific interface address.

Server port

Flag: --port, -p

Default: 8080

Example: just-ssr --port 3333

Use this flag to set the port for the server to listen on. If not provided, it checks process.env.PORT before falling back to 8080. If the port is taken, it will choose a random available port.

Template

Flag: --template, -t

Default: /lib/template.html

Example: just-ssr --template ./dev/template.html

Use this flag to pass in your own template for the entire page's HTML with the --template flag. The template should contain a comment  which serves as the placeholder for rendered app content.

Read the official Vue docs for more information.

👉 Checkout the Template metadata demo to see a working example

Create App

Default: /lib/src/create-app.js

You can pass in a custom create-app.js file to gain more control over your app. For example, you can use this to set up routing or other app-level integrations.

The create-app.js file is introduced in Vue's SSR guide. It must default-export a function that returns the Vue app. Any setup code for the app can live here:

create-app.js

import Vue from 'vue'

/* Import plugins here */

function createApp(App) {
    const app = new Vue({
      render: h => h(App)
    })

    return { app }
}

export default createApp

Pass in the path to create-app.js via the createAppPath property in the Webpack plugin:

  const { JustSsrPlugin } = require('vue-just-ssr');

  module.exports = {
      ...,

      plugins: [
          ...,
          new JustSsrPlugin({
+             createAppPath: './path-to/create-app.js'
          })
      ]
  }

Vue router

If you want to add routing, install Vue Router (npm i vue-router) and add it to your custom create-app file.

The Vue SSR guide recommends organizing your router in a separate file (eg. create-router.js) that exports a createRouter function and importing it into create-app.js.

In your App entry-point, simply render <router-view />.

create-app.js

import Vue from 'vue'
import createRouter from './create-router'

function createApp(App) {
    const router = createRouter()

    const app = new Vue({
        render: h => h(App),
        router
    })

    return { app }
}

export default createApp

create-router.js

import Vue from 'vue'
import Router from 'vue-router'

Vue.use(Router)

function createRouter() {
    return new Router({
        mode: 'history',
        routes: [
            {
                path: '/',
                component: () => import('./pages/Home.vue')
            }
        ]
    })
}

export default createRouter

👉 Checkout the Vue Router demo to see a working example

Client/Server Webpack plugins

If you have plugins that you only want running on the client or server-build, you can wrap them in clientOnly and serverOnly functions.

For example, if you want ESLintPlugin to only run on the client-build, you can modify your Webpack config like so:

  const {
      JustSsrPlugin,
+     clientOnly
  } = require('vue-just-ssr');
  
  module.exports = {
      ...,
  
      plugins: [
          ...,

          new JustSsrPlugin(),

+         clientOnly(
              new ESLintPlugin({
                  files: '**/*.{vue,js}',
                  emitWarning: true
              })
+         )
      ]
  };

privatenumber / vue-just-ssr