https://github.com/privatenumber/vue-just-ssr
🔥 Instantly add a Vue SSR dev-env to your Webpack build
https://github.com/privatenumber/vue-just-ssr
cli ssr vue webpack
Last synced: 7 months ago
JSON representation
🔥 Instantly add a Vue SSR dev-env to your Webpack build
- Host: GitHub
- URL: https://github.com/privatenumber/vue-just-ssr
- Owner: privatenumber
- License: mit
- Created: 2020-09-19T23:21:40.000Z (about 5 years ago)
- Default Branch: develop
- Last Pushed: 2021-08-04T04:27:48.000Z (about 4 years ago)
- Last Synced: 2025-02-16T16:01:46.133Z (8 months ago)
- Topics: cli, ssr, vue, webpack
- Language: JavaScript
- Homepage:
- Size: 279 KB
- Stars: 7
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://cli.vuejs.org).
## 🙋♂️ Why?
- 🏃♂️ **Jump start** Instantly get a Vue dev environment with [SSR](https://ssr.vuejs.org) and [HMR](https://webpack.js.org/concepts/hot-module-replacement/)!
- 🎛 **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
```sh
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.
- [Basic usage demo](https://github.com/privatenumber/vue-just-ssr-demo)
- [Template metadata demo](https://github.com/privatenumber/vue-just-ssr-demo/tree/template-meta)
- [Vue Router demo](https://github.com/privatenumber/vue-just-ssr-demo/tree/vue-router)
- [Vue router + Static site compilation demo](https://github.com/privatenumber/vue-just-ssr-demo/tree/vue-router-html)
## 🚦 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](https://vue-loader.vuejs.org/guide/#manual-setup) (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](https://github.com/privatenumber/vue-just-ssr-demo/blob/master/webpack.config.js).
Add the `JustSsrPlugin` to your Webpack config in the `plugins` array:
```diff
+ 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`.
```diff
{
...,
"scripts": {
+ "dev": "just-ssr --webpack-config "
},
...
}
```
### CLI
Alternatively, use it straight from your commandline via [npx](https://blog.npmjs.org/post/162869356040/introducing-npx-an-npm-package-runner).
```sh
npx just-ssr --webpack-config
```
## 🎨 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](https://superuser.com/a/949522) which means it is not exposed to the rest of your [local area network (LAN)](https://en.wikipedia.org/wiki/Local_area_network). 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`](/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](https://ssr.vuejs.org/api/#template) for more information.
👉 Checkout the [Template metadata demo](https://github.com/privatenumber/vue-just-ssr-demo/tree/template-meta) to see a working example
### Create App
Default: [`/lib/src/create-app.js`](/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](#vue-router) or other app-level integrations.
The _create-app.js_ file is introduced in [Vue's SSR guide](https://ssr.vuejs.org/guide/routing.html#routing-with-vue-router).
It must default-export a function that returns the Vue app. Any setup code for the app can live here:
**`create-app.js`**
```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:
```diff
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](https://ssr.vuejs.org/guide/routing.html#routing-with-vue-router) 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 ``.
**`create-app.js`**
```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`**
```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](https://github.com/privatenumber/vue-just-ssr-demo/tree/vue-router) 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:
```diff
const {
JustSsrPlugin,
+ clientOnly
} = require('vue-just-ssr');
module.exports = {
...,
plugins: [
...,
new JustSsrPlugin(),
+ clientOnly(
new ESLintPlugin({
files: '**/*.{vue,js}',
emitWarning: true
})
+ )
]
};
```