Vue Microblog

# vue-microblog-ts

Small microblogging service written in TypeScript based on Express, Mongoose and Vue.js.

Greenkeeper badge Build status

This project was bootstrapped with Vue CLI 3

# Introduction

This is an example project showing how to build a JavaScript-based CRUD API using TypeScript with some of the latest tools available.

WARNING

This is by no means ready for production and serves only to satisfy your curiosity in case you are planning on building something similar.

# Background

I was originally inspired by Brad Traversy's video series on how to create a Full Stack Vue.js, Express & MongoDB application and wanted to build something similar using TypeScript. With most of the popular front-end frameworks moving in that direction, I figured this was the perfect opportunity to see how Vue is handling this transition after having initially made this announcement back in 2017 and later this in 2018.

TypeScript happens to be a great choice when it comes to building JavaScript-based APIs, since it has very strong type support which comes in handy when dealing with data. It has the added benefit of giving you access to some of the latest features of JavaScript that are still in the planning phase, while still giving you full freedom to write plain old JS if you choose to do so.

At the time of writing (October 2018), the Vue project is still very much in a transition phase when it comes to TypeScript and I have to admit it took some time to piece things together. Documentation on how to tackle specific issues are still buried deep within GitHub issues and Stack Overflow discussions. Having said that, an experienced developer would have no trouble getting by as all the features are already there if you just know where to look.

Hopefully this project will provide you with some insight on how to use these new tools and how to structure your project in case you're thinking on embarking on a similar mission.

Feel free to submit an issue here on GitHub if you have any questions. I'll do my best to share my experiences and redirect you to the right places in case I don't have the answers myself.

# How this works

This project is divided into two parts:

Name Description
Client Vue.js application used to display the content in the browser
Server Node server in charge of serving the static content generated by the Vue CLI and the API endpoints used to communicate with the database

During development, you will need to have both services running simultaneously in the background. In this scenario, you would load the address provided by the Vue CLI service to view your application, while the Node server would only act as a bridge between the client and the Mongo database.

In a production environment however, the Vue CLI service would no longer be needed as it would have generated a static version of the site which the Node server would be more than capable of serving itself, while still handling all the API calls to the database in the background.

You could take this a step further an install a third element such as Nginx to handle the static files, but as things stand this build was more than enough for what I set out to do.

# Project structure

├── babel.config.js        # Config for Babel
├── cypress.json           # Config for Cypress (e2e)
├── dist                   # Production files will be generated here
│   ├── node_modules
│   ├── package-lock.json
│   ├── package.json       # Custom instructions for deployment
│   ├── public             # Production client
│   └── server             # Production server
├── docs                   # VuePress documentation
├── jest.config.js         # Config for Jest (unit tests)
├── jest.setup.js          # Setup file Jest (unit tests)
├── node_modules           # Local dependencies
├── nodemon.json           # Config for Nodemon
├── package-lock.json
├── package.json
├── postcss.config.js
├── public                 # Raw files for serving the client
├── scripts                # Scripts for deployment
├── src                    # Source files
│   ├── client
│   └── server
├── tests                  # e2e and unit tests
├── tsconfig-server.json   # TypeScript config for server
├── tsconfig.json          # TypeScript config for Vue
├── tslint.json            # TSLint file for client and server
└── vue.config.js          # Vue config

# Getting started

Make sure your have all the requirements listed below before proceeding. I have only tested this in a MacOS environment, but all the tools used in this project are universal so you should have no trouble running these on Linux or Windows assuming you follow these instructions in the order provided.

# Requirements

You will only need the third option if you want to try and deploy this to the cloud using the methods described in the Deployment section.

# Installation

Open a terminal window and clone the repository:

$ git clone --depth=1 https://github.com/Phoenix2k/vue-microblog-ts.git

# Dependencies

Go to the newly created folder and install the project dependencies:

$ cd vue-microblog-ts
$ npm install

This will download all the files needed to compile and generate the source files as well as serve the content in development mode, which I suggest you do first before deploying this anywhere.

# Local environment

Create a local .env file based on the example provided with this project:

$ cp .env.example .env

This file holds the following information:

  • MONGODB_URI address where the content is stored
  • NODE_ENV lets the client and server know if are running in development or production mode
  • HEROKU_APP tells the depoloyment script which app it should use if you choose to deploy this to Heroku

# Mongo database

You can set up the database either locally or remotely on a server.

If you're just curious to test this out, you can easily set one up for free on mLab by creating an account and following their instructions or by adding it as an add-on to an existing application on Heroku.

Once you have your database installed, replace the MONGODB_URI inside the .env file located in the root of the project. This will enable your local server to serve content to the client while you are running everything in development mode.

# Development

The source files are located under the src folder.

# Starting the services

You can start each service separetly in your browser using Vue's GUI tool:

$ npm run ui

Activate both dev:client and dev:server tasks to get everything up and running.

Here's a list of the default addresses provided by each service:

Name Address Function
dev:server http://localhost:5000/api Provides API endpoints and communicates with the database
dev:client http://localhost:8080 Serves content with hot-reload for the browser
ui http://localhost:8000 Manages tasks and scripts in the browser

See the Client and Server sections for more information.

If for some reason one of these instances is left running in the background after you're done testing, you can try to find it with this:

$ ps aux | grep node

Look for an application that points to this project, copy the PID and kill the process by replacing 1234 in the following command:

$ kill 1234

# Testing

This project comes with both end-to-end tests and unit tests.

# End-to-end

End-to-end tests are used to test that the flow of the application is performing as designed from start to finish. For this project, I chose Cypress since it was one of the options provided by Vue CLI.

At the time of writing it only supports a headless version of Chrome and while ideally you would test an application on a variety of browsers, the solution offered by Cypress was more than enough for this project.

To run the end-to-end tests, enter the following command:

$ npm run test:e2e

This will make sure the app is responding and that the Vue Router is functionning properly.

The tests are located under the tests/e2e folder.

# Unit testing

Unit tests are used to test various aspects of an application, from rendering components correctly to testing out actual functionality and state management.

The tests in this project are orchestrated by Jest which was originally developed by Facebook for internal testing and later released into the wild as an open source project.

To give this a spin, enter the following command in your terminal:

$ npm run test:unit

You can find the individual tests under the tests/vue folder.

# Building for production

Build both applications for production:

$ npm run build

Launch the production server:

$ cd dist
$ npm start

This will serve the static files from the public folder (also located under dist) and provide the necessary endpoints for the API.

TIP

If you are planning on running the production versions from your local machine, you will need to make a copy of the root .env file to the dist folder in order for Node to understand how to connect to the database.

The contents of the dist folder is meant to be run in an actual production environment where these variables are already available.

# Sources

# License

MIT

Introduction to the client →