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.
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.