epicenter v0.5.0
Epicenter
An opinionated plaform for building a nodejs backed web product.
Introduction
With Nodejs finally announcing version 4.x and and Long Term Support we are arriving at a time when Nodejs is finally ready for prime time usage. Companies like Netflix, Uber, Paypal, Medium, and others have voiced their support.
The hard part is figuring out how to get started. I've been down several roads playing with various technologies and patterns for building a node application. Today I share with you my preferred method of buidling a website or web application using Nodejs. This project is called Epicenter.
Philosophy
The philosophy behind Epicenter can be broken down into three major points:
1) There is no silver bullet
So let's defer decisions on the "best" way to implement your site and leave options open. That is why we begin with an Express.js server environment that is completely under your control. Epicenter then gives you, by default, 3 forms of application development environments.
They all work in unison so use any one of these environments, a mixture, or all. You get, built in:
- Static file serving
- Precompiled static file serving
- and Server managed routes
2) Context switching is painful
So let's use Javascript on both the client, and the server. Write a javascript library and use it BOTH server side and client side. Don't write your logic twice. Don't switch mentally between javascript and another back-end language. Just build.
3) Embrace web development innovation now
Javascript ES5 is not fun to use and full of headache. Unfortunately it's the only version of Javascript that runs on all browsers and back-ends. So let's write some ES6 (or if you are feeling adventurous, ES7) and compile it down to ES5 on BOTH the server AND the client. Write your code once, compile it uniformly, and deploy anywhere. (powered by Babel and Webpack)
While we're at it, let's mix in pre-compiled SCSS and HTML Templating (Nunjucks).
Live reload of BOTH the server and the client are also in play. They are not perfect yet, but they are coming.
Finally, EVERYTHING is customizable. Modify your webpack config and tweak everything to behave precisely how you want it to.
What you get
'epicenter init ' drops a ready-to-run demo application in the directory of your choice. A quick 'npm install' and then a 'npm run watch' will get you a running site with all the trimmings. Start customizing from there!
A breakdown of the folder structure is as follows:
./package.json - a default package.json with all the default dependencies
./webpack.config.js - the webpack configuration, customize everything
./webpack.watch.service.js - config for epicenter's live server reload
./app/server.js - a lightweight Express.js web server
./app/app.js - the root of the Express.js web server application
./app/precompiled/ - the home for all .nunj, .scss, and .js(x) files
./app/static/ - the home for all static resources (ie. .jpg, .svg, .pdf)
./app/source/ - your application code including .js(x), .nunj, and .scss
When webpack executes on this project it will compile the server.js as webpack's first entrypoint. It will then compile each file inside of ./app/precompiled/ as their own unique entrypoints.
When you boot up the application the default app.js hosts checks requests against a dynamic route, if the route cannot handle the request it tries to find the path among the compiled files that came from the ./app/precompiled/ folder. If it still has not handled the request, it looks in the ./app/static/ sources.
Both the server.js, and any precompiled resources (.nunj, .scss, and .js) can import resources from the static ./app/source/ folder as if it was located in the same directory as the importing resource.
More documentation to come.
Getting started
Install epicenter as a global binary. This will give you the 'epicenter' command to use anywhere in your terminal.
npm install -g epicenter
Initialize a new epicenter application
epicenter init <path to new application>
cd <path to new application>
npm install
npm run watch
Now browse to http://localhost:8080
More to come
This is merely the foundation of the project. More to come!
Known issues
At the moment we are having trouble with Windows users who have spaces in their directory names. We will address this shortly.