newww

We're using Hapi as our framework for the npm website. We wrote all about why we chose Hapi in a blog post.

If you'd like to contribute to this project, please do!

Application Structure

Let's take a tour of the app.

Assets

The assets directory contains all the frontend stuff: JavaScript, stylesheets, images, fonts, robots.txt, favicon.ico, etc. The gulp process watches this directory for file changes, and outputs everything to the static directory, which is ignored by git to prevent automated version control noise.

Browserify assets/scripts/index.js
Concatenate non-browserify JavaScripts in assets/scripts/vendor

Styles

We're using Stylus, a CSS preprocessor with clean syntax and all the bells and whistles one would expect from a CSS preprocessor like variables, mixins, color manipulation functions, autoprefixing, etc. It's less of a hassle than Sass because it doesn't have C or Ruby dependencies.

assets/styles/index.styl is the master stylesheet, which is converted by the gulp process to static/styles/index.css.

For more information, see the style guide.

Templates

We're using Handlebars as our templating engine. Server-rendered templates live in templates. Frontend templates live in assets/templates. They are browserified into the bundled JS file using the hbsfy transform.

Partials

Handlebars partials are handy for markup that is needed in more than one place. All the partials are located in templates/partials. Every .hbs file in the partials directory becomes avaiable in all handlebars templates. For a good explanation of how to use partials, check out Passing variables through handlebars partial on Stack Overflow, or search for {{> in this codebase to see how we're using them.

Locales

A rudimentary localization effort is under way. The locales directory contains javascript files that export translations of various strings used throughout the app.

Content Security Policy (CSP)

We use the blankie Hapi plugin to enforce a strict content security policy that disallows execution of unsafe Javascript. It's defined in csp.js.

Routes

Every route in the application is defined in routes.js.

Handlers

Handlers (sometimes called controllers) are functions that accept two parameters: request and reply.

The request parameter is an object with details about the end user's request, such as path parameters, an associated payload, authentication information, headers, etc.

The second parameter, reply, is the method used to respond to the request.

Here's an example of a simple handler:

server.route({
    method: 'GET',
    path: '/',
    handler: function (request, reply) {
        reply('Hello!');
    }
});

The above handler is defined inline, but most of the handlers in this application are defined in their own file in the handlers directory.

Tests

We're using Lab as our testing utility and Code for assertions.

npm install
npm test

If you have npm 2.0.0 or greater installed (which you should), you can pass additional arguments to scripts. This handy feature allows for more granular control of the tests you want to run:

# a directory
npm test -- test/handlers

# a file
npm test -- test/models/user.js

Code

We're using semi-colons and comma-last. No rhyme or reason; just cuz.

Running the server locally

It is not currently possible for non-employees to run the development server. This is being tracked at github.com/npm/newww/issues/761.

# run redis in a background process
redis-server&

# copy environment-based config/secrets
cp .env.example .env

# install deps
npm install

# run the hapi server
npm run dev

The server should be running at localhost:15443.

If you have any trouble getting the site running locally, please open an issue and we'll help you figure it out.

mfunkie/newww