DEV Community: Robert

How to create amazing SSR website with Wagtail 2 + Vue 3

Robert — Tue, 01 Sep 2020 11:05:10 +0000

Why do I do that?

I want to share some tools combined with best practices.
This setup is flexible enough to create huge web projects. Indeed this is just a general idea and proof of concept, how we can combine Vue3 with Django based CMS.

In case you are to lazy or to excited to see it in action, you can go directly to the github repo.

If you like django and python you will love wagtail CMS. Check it out at: https://wagtail.io/

You heard a lot about the new version of vue? It's amazing. Let's try to combine it with the best Python CMS and make sure that we still have SSR (Server Side Rendering) and make use of the popular package django_webpack_loader

Let's dive in.

First we create a docker-compose.yaml file:

version: "3"

services:
    cms:
        restart: always
        image: cms/wagtail
        build:
            context: ./cms
        volumes:
            - ./cms:/code/cms
            - ./frontend:/code/cms/frontend
        ports:
            - 8000:8000
        links:
            - frontend

    frontend:
        restart: always
        image: frontend/node
        build:
            context: ./frontend
        command: yarn serve
        ports:
            - 8080:8080
        volumes:
            - ./frontend:/code/cms/frontend

We generate wagtail project inside the project folder and name it cms:

pip install wagtail
wagtail start cms

For the frontend part create a frontend folder

mkdir frontend

After this you can create package.json file inside this folder.

{
  "name": "frontend",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "scripts": {
    "serve": "webpack-dev-server --host 0.0.0.0"
  },
  "dependencies": {
    "vue": "3.0.0-rc.9",
    "webpack-bundle-tracker": "0.4.3"
  },
  "devDependencies": {
    "@vue/compiler-sfc": "3.0.0-rc.9",
    "ts-loader": "8.0.3",
    "typescript": "4.0.2",
    "vue-loader": "16.0.0-beta.5",
    "webpack": "4.44.1",
    "webpack-cli": "3.3.12",
    "webpack-dev-server": "3.11.0",
    "yarn": "1.22.5"
  }
}

tsconfig.json:

{
  "compilerOptions": {
    "allowJs": true,
    "allowSyntheticDefaultImports": true,
    "declaration": false,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "module": "es2015",
    "moduleResolution": "node",
    "noImplicitAny": false,
    "noLib": false,
    "sourceMap": true,
    "strict": true,
    "strictPropertyInitialization": false,
    "suppressImplicitAnyIndexErrors": true,
    "target": "es2015",
    "baseUrl": "."
  },
  "exclude": [
    "./node_modules"
  ],
  "include": [
    "./src/**/*.ts",
    "./src/**/*.vue"
  ]
}

webpack.config.js

const path = require('path')
const { VueLoaderPlugin } = require('vue-loader')
const BundleTracker = require('webpack-bundle-tracker');

module.exports = (env = {}) => {
  return {
    mode: env.prod ? 'production' : 'development',
    devtool: env.prod ? 'source-map' : 'cheap-module-eval-source-map',
    entry: path.resolve(__dirname, './src/main.ts'),
    output: {
      path: path.resolve(__dirname, './dist'),
      publicPath: "http://0.0.0.0:8080/"
    },
    module: {
      rules: [
        {
          test: /\.vue$/,
          use: 'vue-loader'
        },
        {
          test: /\.ts$/,
          loader: 'ts-loader',
          options: {
            appendTsSuffixTo: [/\.vue$/],
          }
        },
      ]
    },
    resolve: {
      extensions: ['.ts', '.js', '.vue', '.json'],
      alias: {
        'vue': '@vue/runtime-dom'
      }
    },
    plugins: [
      new VueLoaderPlugin(),
      new BundleTracker({ filename: './webpack-stats.json' })
    ],
    devServer: {
      headers: {
        "Access-Control-Allow-Origin": "\*"
      },
      public: 'http://0.0.0.0:8080',
      inline: true,
      hot: true,
      stats: "minimal",
      contentBase: __dirname,
      overlay: true
    }
  };
}

Dockerfile

FROM node:12.15.0 as base

WORKDIR /code/cms/frontend
COPY ./package*.json ./
RUN yarn install
COPY . .

Than you can create frontend/src folder with following files inside.
main.ts

import { createApp } from 'vue';
import CountButton from './components/count_button.vue';

createApp(CountButton).mount('#vue-count-button'); // This selector name will be used in wagtail / django template.

The idea is to create each vue instance for each component which has to be binded to the django template.

shims-vue.d.ts

declare module "*.vue" {
  import { defineComponent } from "vue";
  const Component: ReturnType<typeof defineComponent>;
  export default Component;
}

Create a frontend/src/utils/ folder
and following django-variables.js file. This get method will help us to get properties directly from django templating to our vue instance.

function _getSingle(id) {
  if (!document.querySelector(`#${id}`)) {
    console.error(`Selector #${id} could not be found. Please check your django templates.`);
    console.error(`
      You are probably missing something like {{ value|json_script:'${id}' }}
      in your django template.`
    );
    return "";
  }
  return document.querySelector(`#${id}`).textContent.replace("\"", "");
}

function get(...args) {
  let obj = {};
  args.forEach((id) => {
    obj[id] = _getSingle(id)
  })
  return obj;
}

export {
  get
}

You can create a component in frontend/src/components
count-button.vue component

<template>
  <div>
    <h2>This is a Vue 3 component!!</h2>
    <button @click="increase">Clicked {{ count }} times.</button>
  </div>
</template>
<script lang="ts">
import { ref } from 'vue';
import { get } from '../utils/django-variables';
export default {
  setup() {
    const djangoVariables = get('header_title', 'header_title2');
    console.log(djangoVariables);
    const count = ref(0);
    const increase = () => {
      count.value++;
    };
    return {
      count,
      increase
    };
  }
};
</script>

For the CMS Part you need to install django_webpack_loader
Add following line to requirements.txt in cms folder

...
django-webpack-loader==0.6.0

In order to apply this change you need to build your cms container. Simply run: docker-compose build cms

Add 'webpack_loader' to your INSTALLED_APPS in cms/cms/settings/base.py

INSTALLED_APPS = [
    'home',
    'search',

    'wagtail.contrib.forms',
    'wagtail.contrib.redirects',
    'wagtail.embeds',
    'wagtail.sites',
    'wagtail.users',
    'wagtail.snippets',
    'wagtail.documents',
    'wagtail.images',
    'wagtail.search',
    'wagtail.admin',
    'wagtail.core',

    'modelcluster',
    'taggit',

    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    'webpack_loader'
]

On the bottom of cms/cms/settings/base.py add following dict:

WEBPACK_LOADER = {
    'DEFAULT': {
        'CACHE': True,
        'BUNDLE_DIR_NAME': '/bundles/',  # must end with slash
        'STATS_FILE': '/code/cms/frontend/webpack-stats.json',
    }
}

In your base.html template you will need to add following tags:

{% load render_bundle from webpack_loader %}

{% render_bundle 'main' %}

Example cms/cms/templates/base.html:

{% load static wagtailuserbar %}
{% load render_bundle from webpack_loader %}

<!DOCTYPE html>
<html class="no-js" lang="en">
    <head>
        <meta charset="utf-8" />
        <title>
            {% block title %}
                {% if self.seo_title %}{{ self.seo_title }}{% else %}{{ self.title }}{% endif %}
            {% endblock %}
            {% block title_suffix %}
                {% with self.get_site.site_name as site_name %}
                    {% if site_name %}- {{ site_name }}{% endif %}
                {% endwith %}
            {% endblock %}
        </title>
        <meta name="description" content="" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />

        {# Global stylesheets #}
        <link rel="stylesheet" type="text/css" href="{% static 'css/cms.css' %}">

        {% block extra_css %}
            {# Override this in templates to add extra stylesheets #}
        {% endblock %}
    </head>

    <body class="{% block body_class %}{% endblock %}">
        {% wagtailuserbar %}

        {% block content %}{% endblock %}

        {# Global javascript #}
        {% render_bundle 'main' %}
        <script type="text/javascript" src="{% static 'js/cms.js' %}"></script>

        {% block extra_js %}
            {# Override this in templates to add extra javascript #}
        {% endblock %}

    </body>
</html>

Now in order to load our count button vue component to a template, we need just to reference the id defined in main.ts

<div>
    <div id="vue-count-button"></div>
    <div id="vue-sidebar"></div>
</div>

To pass some variables from template to vue components. Just add:

{{ block.value|json_script:'header_title'}}

Inside the template.
and add:

import { get } from '../utils/django-variables';
...
const djangoVariables = get('header_title');
...

Example cms/home/templates/home/home_page.html:

{% extends "base.html" %}
{% load static %}
{% load wagtailcore_tags %}

{% block body_class %}template-homepage{% endblock %}

{% block extra_css %}


{% comment %}
Delete the line below if you're just getting started and want to remove the welcome screen!
{% endcomment %}
<link rel="stylesheet" href="{% static 'css/welcome_page.css' %}">
{% endblock extra_css %}

{% block content %}

<div>
    <div id="vue-count-button"></div>
    <div id="vue-sidebar"></div>
</div>
<article>
    {% for block in page.body %}
        {% if block.block_type == 'heading' %}
            {{ block.value|json_script:'header_title'}}
            {{ block.value|json_script:'header_title2'}}
            <h1>{{ block.value }}</h1>
        {% endif %}
        {% if block.block_type == 'paragraph' %}
            <p>{{ block.value }}</p>
        {% endif %}

    {% endfor %}
</article>


{% endblock content %}

Finally

Run yarn install in your frontend folder
Run docker-compose exec cms bash python manage.py migrate to run wagtail migrations
Open localhost:8000

Check our the working example on github:

https://github.com/devs-group/wagtail-vue

If you apply this rules, your development will change dramatically

Robert — Mon, 01 Jun 2020 21:31:50 +0000

As we developers rely on agile software development, we believe software has to be built in a professional way. This mindset brought us to the following rules:

Automate setup as much as possible to reduce time and costs for new developers or changing environments.

Good programmers are lazy programmers. So we don’t want to repeat the same job every day or even multiple times per day. For this kind of jobs we have our great employees called “Computers”. Yes we know computer is a tool but sometimes we can treat them as our friendly employees. Be kind to computers and write them a very detailed recipes (in any programming language), how to help us at work, be more productive and stay lazy.

Offer maximum portability for having the availability to move the software to any place at any time.

Today we could deploy on AWS tomorrow we better deploy on DigitalOcean or maybe a service which is much cheaper? And in one year there is another super duper cloud provider which rules the world. We want to be ready to move to the best service in no time. Btw. “portability” is defined as a software quality attribute ISO/IEC9126.

Use the cloud and modern deployment strategies to avoid administration work.

This is also related to setup automation. We use Continuous Integration and we also have to deploy automatically. We see deployment setup as one of the first steps when starting a software project. Modern Continuous Integration tools like Circle CI, Gitlab, Travis or Jenkins have great support for building and managing docker containers. We use kubernetes to orchestrate those containers on the servers because it is a nice handy tool.

Get rid of differences between development / staging / production, to minimize unexpected issues.

We all heard the following sentence: “It works on my machine”. Making sure, there are no differences between multiple environments is very important to avoid unexpected bugs after we deploy from one environment to another. Minimizing differences can be ensured with Virtual Machines or the right usage of our lovely Docker. One another thing is data. Data has to be migrated properly. Often missing datasets or different data structure causes bugs. For example copying some of data from production to staging environment or using good data fixtures could sometimes be a very good idea.

Be ready to scale at any time, without big architecture changes or development works.
You will never know how big your next application will be. To be able to handle million of users on your system you will need to scale fast. This should be a criteria even before you start coding. Using kubernetes properly will make scaling quite easy.
Monitor applications logs and resources to be informed about issues before your customer does that.
We have to expect bugs in our software. Even if we think we write perfect bug free code. When a doctor is doing an operation he always needs to see inside the body, monitor the pulse, the heart rate etc. That is very similar to making code changes or to implement new functionality. We need some indicators for heart rate and pulse of our software and we need a possibility to always look inside by reading the logs. Use monitoring like prometheus, define rules for your logs, write them, collect them and read them. Mail or slack notification might be also useful.
Use best practices and contribute to open source projects.

We don’t have to reinvent the wheel, we are not alone with our problems.
Before we start code a complex algorithm or write a component, we always should look if there is any implementation done yet. When yes, just use it. For missing features you can just make a pull request or create a for of repository. Developers are kind and want to help each other. This is what open source is all about.

Implement the “green light” which tells us, if our product is still working as we expect.

Wouldn’t it be awesome if some indicator can tell you, if you broke any function of your software or not? Write tests and run them on your machine and in the CI before you deploy.

Code structure has to be clearly defined and understood inside the team.

A codebase is defined as a git repository
One git repository has a file called README.md which describes: What this repository is good for, How to run checks and tests, How to contribute, How to deploy
Every codebase can be a port of a distributed system and is runnable and deployable as it is.
When a codebase has to be shared between two or more repositories, we call it a “dependency” and should be managed and versioned by pip, npm, maven, composer or other dependency management tools.

Define a code style for your codebase and check it every time changes are made to improve readability
Don’t hold any state for your application on the server.
All state data should be saved in external data stores “Databases” or “File systems” and not on process it is running.
Only cache can be saved on the machine “RAM” or “File system”
Administrative commands like DB migrations, running tests, deployment command, should be defined in each codebase.
Keep your Tasks, MRs and commits small.
Small tasks are better understood and motivation is higher to accomplish more tasks per day
Small MRs are always better reviewed
Small commits describe your work better. While Know-How transfer is more precise. Quality will be improved