Open sourcing kraken.js


kraken-logoIt wasn’t far into our move to node.js that we began to notice an opportunity to contribute back to the community. There were plenty of web application frameworks out there, but items like localization, country adaption, security, and scalability for large development teams were largely missing. We deal with money, and we do it in 193 markets covering 80 languages and 26 different currencies. That’s a lot of complexity and requires multiple teams to develop. Kraken was created to make this process easier.

What kraken offers

Kraken uses the popular express web application framework as a base platform and adds environment-aware and dynamic configuration, advanced middleware capabilities, application security, and lifecycle events. These features make Kraken ideal for enterprise-size companies where consistency across teams is needed, but also useful for node.js beginners who want to focus on building their application and not the application’s framework.

Pre-configured, but customizable

All of the technologies you need to build a web application are pre-configured and stitched together for you by generator-kraken. Creating a new kraken app is as easy as running yo kraken and answering a few questions.

By default, this scaffolding includes dust for templates, LESS for CSS preprocessing, RequireJS for JavaScript modules, and Grunt for task handling. This is our recommended setup, but using different technologies is supported as well.


If you’ve used express before you’ve probably written code to configure how your cookies are parsed, if you have a favicon or not, how you’re accepting multipart forms, etc. It’s extremely flexible, but that code can add complexity and, more importantly, if your applications are spread across teams they’re not guaranteed to be doing it the same way. Kraken solves this by moving this setup out of the code and into configuration files.

Configuration example

Application and middleware configuration is stored in JSON files, creating a consistent implementation and removing the need for tribal knowledge when configuring items, e.g. does bodyParser need to come before cookieParser or vice-versa?

These files are also environment-aware, so overriding values when you’re in development, debug, or test mode is easy. To override a value in config/app.json for development you would create config/app-development.json with the delta and then start your app using NODE_ENV=development node index.js.

Globalization and localization

As an application grows in popularity it’s developers inevitably need to support different regions. At PayPal we support 193 countries across the globe.

Applications created via generator-kraken have built-in support for externalized content when using dust templates. This content is stored in it’s own file using key/value pairs. We opted to not use JSON or any other complex format and instead opted for a simpler data structure which was easy enough to be hand edited if needed, but powerful enough to support the flexibility we needed.

Each template has an implicit binding to a content file of the same path and will automatically resolve strings within them. In other words, if you have templates/account/user.dust then content will be merged from locales/DE/de/account/ for German users. This removes the hassle of needing to manually wire up your content source.

Content example

Shortly, we’ll also release support for template specialization when using dust in Kraken. Experiences often need to deviate based on locale, but also for AB tests and device types. It’s subpar to have this logic cluttering your code, and specialization solves this.

Application security

Security is important to us and, while there are a good amount of best practices available for web applications, most are typically not enabled by default. Kraken enables these for you and uses configuration to set up smart defaults. A few of the more useful ones to call out are:

  • CSRF – Cross-site request forgery support is enabled by default. A token will be added to your session and if the user is going to perform any data changing method, e.g. POST, PUT, DELETE, then the template must return the token value. This protects against malicious websites changing data on your user’s behalf.
  • XFRAMES – Using an HTML frame element to frame another website and trick users into performing actions they did not intend is called click-jacking. XFRAMES headers protect against this by restricting who can frame the web application. By default this is set to SAMEORIGIN, which means only you can frame your website.
  • CSP – Content Security Policy enables to you tell the browser what type of resources are allowed and enabled for your web application.

How open source has changed PayPal

Kraken was the first major release for PayPal into the open source world and has been hugely successful in changing the way we think about software. In a way, it helped paved the way for us to hire Danese Cooper as our first head of open source at PayPal! We have historically been a company who kept to themselves and thus a lot of code which may have been useful to the community was instead developed in a proprietary manner.

Kraken was built to be the opposite of this: it is publicly available. This allowed us keep out what I consider PayPal’isms – the secret sauce specific to PayPal – and to give back to the node community and fill any gaps for others benefit.

The node community itself has been very welcoming and we’ve seen both great interest in our adoption of node and multiple external contributions the kraken codebase. This has been inspiring and has definitely solidified that we made the right choice in going open source.

Try it out

If you’re interested in trying out kraken, head on over to where you can find instructions and sample code to get you on your way. You can find other open source offerings from PayPal at

If any of this sounds interesting come work for us!

Jeff Harrell

A designer turned engineer, I’ve been making applications for the web for years and enjoy all aspects from conceptualization and design to the engineering bits which drive them. Simply put, I love building great products.

During the day, you can find me at PayPal HQ where I lead UI Engineering Architecture. My focus is disruptive change for both products and our technology stack, and I’m excited that we’re making strides in this direction.