# Getting Started: Hitchy & Vue

Hitchy as a framework is suitable for implementing a server-side business logic. Even though you could also have some server-side rendering of views, implementing separate client-side application is rather common nowadays.

In this tutorial we'll combine Hitchy with Vue (opens new window) to achieve that.

TIP

By combining Hitchy with a client-side framework such as Vue (opens new window), your project is reducing load on server by moving GUI logics to the client. This is beneficial with regard to handling lots of requests on server side and to implementing stateful GUIs e.g. by managing cookies or similar. Your project will run faster even on smaller servers.

# Prerequisites

First, a local installation of Node.js (opens new window) is required.

Vue development probably depends on packages that require additional installation of Python (opens new window) on your computer. Current versions of Node.js installer offer installation of additionally required build tools. When accepting that offer it will cover Python installation.

Python Required?

This step is basically optional as long as there are no dependencies that rely on binary libraries to be compiled on your computer. You may control this by disabling certain features such as CSS pre-processors on creating your Vue application in next section.

Vue comes with a CLI that must be installed globally using npm which in turn has been installed as part of Node.js.

npm install -g @vue/cli

In addition, we suggest installing git (opens new window) and docker (opens new window) on your computer.

# Create a Vue Project

Vue Project Exists Already?

Just skip this part!

Start with creating a Vue project using Vue CLI:

vue create myapp

This will ask questions about features and tools you like to use with your application before creating a new sub-folder named like your app: myapp. This process may take a while.

Enter that folder:

cd myapp

Open file .gitignore and append these lines:

data
server/public
server/config/local.js

# Add Hitchy

Hitchy will be integrated with your Vue application. Its code is going to reside in sub-folder named server:

mkdir server

Additional dependencies are required:

npm install @hitchy/core @hitchy/plugin-static @hitchy/plugin-odem @hitchy/plugin-odem-rest
npm install -D @hitchy/plugin-proxy
  • @hitchy/core is the core of Hitchy capable of handling requests and processing routing tables.
  • @hitchy/plugin-static is extending Hitchy for statically exposing files in a local folder. It will be used in a production setup for serving files of your application as built by Vue.
  • @hitchy/plugin-proxy is another extension to Hitchy implementing a basic reverse proxy. It is used to expose Vue's development server instead of the built files during development.
  • @hitchy/plugin-odem is rather optional here. As an extension to Hitchy, it is implementing a simple ODM for managing data on server-side.
  • @hitchy/plugin-odem-rest is an addition to that ODM feature exposing all models over REST API without any extra line of code.

Adjust the file package.json for adding scripts named start and start:dev in scripts:

{
	...
	"scripts": {
		...
		"start": "hitchy --project=server --plugins=. --ip=0.0.0.0",
		"start:dev": "hitchy --project=server --plugins=. --ip=0.0.0.0 --development --debug"
	},
	...
}

# Add Code Quality Tools

We suggest using these tools for testing your code:

npm install -D eslint-plugin-promise eslint-config-cepharum mocha should @hitchy/server-dev-tools

You should create a file named server/.eslintrc containing:

{
	"extends": [
		"eslint-config-cepharum"
	]
}

Optionally add scripts named server:test and server:lint in package.json file:

{
	...
	"scripts": {
		...
		"server:lint": "eslint server",
		"server:test": "mocha --ui tdd --recursive 'server/test/**/*.spec.js'"
	},
	...
}

# Wrap Vue in Hitchy

Hitchy is meant to deliver output of Vue.

# Development Setup

When developing Vue applications, there is a local server presenting current state of your application as a live preview. It is started with

npm run serve

You must start this server in addition to Hitchy yourself.

Create a file named myapp/server/config/proxy.js containing:

module.exports = function (options) {
	return {
		proxy: options.arguments.development ? [{
			prefix: "/",
			target: "http://127.0.0.1:8080/"
		}] : [],
	};
};

TIP

This configuration file complies with a special pattern to configure server in different ways depending on argument --development provided on command line or not.

This is setting up reverse proxy plugin to forward all requests not matching any more specific route to that development server of Vue.

# Production Setup

In production setup, there are static files built with Vue, only. Hitchy is required to serve those instead of some local development server's output.

Create a file myapp/server/config/static.js containing

module.exports = function (options) {
	return {
		static: options.arguments.development ? [] : [{
			prefix: "/",
			folder: "public",
			fallback: "index.html"
		}],
	};
};

This causes Hitchy to statically expose all files in the folder myapp/server/public.

Edit file named myapp/vue.config.js to customize option outputDir so that Vue is putting built files of application into the desired folder. Create the file if it's missing.

module.exports = {
  lintOnSave: false,
  outputDir: "server/public"
}

# Test Your Setup

# Development Setup

Invoke

npm run serve

for starting development server of Vue and

npm run start:dev

for starting Hitchy. Observe the latter script's output for picking URL to open in a browser. This should present home screen of Vue skeleton created before.

# Production Setup

Built application files with

npm run build

It should put files into folder myapp/server/public. This time, start Hitchy by invoking

npm run start

Again, try to request URL presented by the latter script after a few moments in your browser. It should present the same home screen of Vue as before.

# Customize Hitchy

# Use Persistent Data Backend

For Hitchy's ODM persistently saving data you need to set up an adapter. You can go without, but the ODM is using in-memory backend by default, thus loosing all data on restarting server-side of application.

Create a file myapp/server/config/database.js with following content:

const Path = require( "path" );

module.exports = function() {
	return {
		database: {
			default: new this.runtime.services.OdemAdapterFile( {
				dataSource: Path.resolve( __dirname, "../../data" ),
			} ),
		},
	};
};

This is selecting another ODM backend shipped with ODM plugin itself for storing data in local file system. The configured folder will be myapp/data and that's why it has been listed in .gitignore file created earlier.

Production Use

Using this backend might be an option for production setup, as well.

  • You shouldn't use it if you expect a huge number of records and/or a lot of requests accessing them.

  • You can't use it on running single instance of your application in a cluster unless it has reliable and exclusive access on a particular filesystem at any point in time (like a network share or similar).

  • Eventually, you can't use it on running multiple instances of your application in a cluster even though all instances are accessing the same set of files.

Please refer to @hitchy/plugin-odem-etcd (opens new window) for using an etcd cluster instead of local files.