<h1 align="center"> <a href="https://ladjs.github.io/lad/"><img src="media/lad.png" alt="lad" /></a> </h1> <div align="center"> <a href="https://join.slack.com/t/ladjs/shared_invite/zt-fqei6z11-Bq2trhwHQxVc5x~ifiZG0g"><img src="https://img.shields.io/badge/chat-join%20slack-brightgreen" alt="chat" /></a> <a href="https://travis-ci.org/ladjs/lad"><img src="https://travis-ci.org/ladjs/lad.svg?branch=master" alt="build status" /></a> <a href="https://codecov.io/github/ladjs/lad"><img src="https://img.shields.io/codecov/c/github/ladjs/lad/master.svg" alt="code coverage" /></a> <a href="https://github.com/sindresorhus/xo"><img src="https://img.shields.io/badge/code_style-XO-5ed9c7.svg" alt="code style" /></a> <a href="https://github.com/prettier/prettier"><img src="https://img.shields.io/badge/styled_with-prettier-ff69b4.svg" alt="styled with prettier" /></a> <a href="https://lass.js.org"><img src="https://img.shields.io/badge/made_with-lass-95CC28.svg" alt="made with lass" /></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/ladjs/lad.svg" alt="license" /></a> </div> <br /> <div align="center"> Lad is the best <a href="https://nodejs.org">Node.js</a> framework. Made by a former <a href="https://github.com/expressjs/express">Express</a> TC and <a href="https://github.com/koajs/koa">Koa</a> team member. </div> <div align="center"> <sub> A lad that fell in love with a <a href="https://lass.js.org"><strong>lass</strong></a> • Built by <a href="https://github.com/niftylettuce">@niftylettuce</a> and <a href="#contributors">contributors</a> </sub> </div> <hr /> <div align="center"> <h3><u>Project Spotlight:</u> Forward Email @ <a href="https://forwardemail.net" target="_blank">https://forwardemail.net</a> (made with Lad)</h3> <h4><u>Live Framework Demo:</u> <a href="https://lad.sh" target="_blank">https://lad.sh</a></h4> </div> <hr /> <div align="center">:heart: Love this project? Support <a href="https://github.com/niftylettuce" target="_blank">@niftylettuce's</a> <a href="https://en.wikipedia.org/wiki/Free_and_open-source_software" target="_blank">FOSS</a> on <a href="https://patreon.com/niftylettuce" target="_blank">Patreon</a> or <a href="https://paypal.me/niftylettuce">PayPal</a> :unicorn:</div>

Features
Get Started
- Requirements
- Install
- Usage
- Configuration
- Tutorials
- Community
Architecture
Principles
Related
Contributing
Contributors
Trademark Notice
License

Features

Lad boasts dozens of features and is extremely configurable.

Microservices

These microservices are preconfigured for security, performance, and graceful reloading.

Webapp server → web.js
API server → api.js
Job scheduler → bree.js
Proxy server → proxy.js

Front-end

Browser linting using [eslint-plugin-compat][] and [browserslist][] (see .browserslistrc for the default config)
[Pug][] template engine (you can easily use [Moon][], [Vue][], [React][], or [Angular][], though typically [you aren't going to need it][yagni])
[Gulp][] (latest version 4.x)
[Sass][]
[PostCSS][] (with [font-magician][], [import-url][], [font-grabber][], [base64][], and [cssnext][] pre-configured)
[Bootstrap][]
[Font Awesome][font-awesome]
[SpinKit][]
[SweetAlert2][]
[Dense][]
[Waypoints][]
[LiveReload][]
…

Back-end

Redis, sessions, and flash toast and modal [SweetAlert2][] messages (uses [ioredis][] which has support for [Cluster][redis-cluster], [Sentinel][redis-sentinel], and more)
Koa-based webapp and API servers (uses HTTP/2 for production!)
Pagination built-in (using [ctx-paginate][])
RESTful API with BasicAuth and versioning
Automated job scheduler with cron and human-readable syntax (backed by [Mongoose][] and [Bree][])
Passport-based authentication and group-based (Unix-like) permissioning
Stripe-inspired error handling
Mongoose and MongoDB with common database plugins
Email template engine with [Nodemailer][] and local rendering
Proxy eliminates need for Nginx reverse-proxy or Apache virtual hosts
Multilingual through built-in i18n translation support (see configuration)
Automatic phrase translation with Google Translate
Sitemap generator for simple SEO
…

Translation

Finally a framework that solves i18n everywhere; complete with automatic translation.

Translation constants built-in so you [don't repeat yourself][dry]
Webapp error messages and templates are translated
Emails are translated
API responses are translated
Database errors are translated
Authentication errors are translated
…

Email Engine

Our beautiful email engine uses [email-templates][] (which is also made by the creator of Lad)!

Test your emails locally with automatic browser-rendering on the fly
Automatically inlines CSS for cross-browser and cross-platform email client support
Use [Bootstrap][] in your email template designs
Reuse your existing CSS and webapp styling
Use any template engine (defaults to Pug)
[Render custom fonts in emails with code][custom-fonts-in-emails]
[Add icons with Font Awesome with code][font-awesome-assets]
[Automatically avoid email client caching][nodemailer-base64-to-s3]
Include any image you want and it will be properly rendered
Rids the need for awkward embedded image CID attachments
…

Error Handling

We've spent a lot of time designing a beautiful error handler.

Supports text/html, application/json, and text response types
User-friendly responses
HTML error lists
…

See [koa-better-error-handler][] for a complete reference.

Performance

Compression and zero-bloat approach
Stream-based file uploading
Graceful reloading, shutdown, and reconnection handling
Manifest asset revisioning
Amazon S3 and CloudFront ready
…

Security

Database security plugins and helpers
Automated tests and code coverage
CORS, SameSite set to "lax" ([an alternative to CSRF][csrf-alternative]), CSRF (since [not all browsers][csrf-caniuse] support SameSite yet) XSS, and rate limited protection
Dotenv support for environment-based configurations
App, user, and request-based logging
SSL-ready (see instructions below)
…

Get Started

We strictly support Mac and Ubuntu-based operating systems (we do not support Windows).

Requirements

Please ensure your operating system has the following software installed:

[Git][] - see [GitHub's tutorial][github-git] for installation
[Node.js][node] (v10+) - use [nvm][] to install it on any OS
- After installing nvm you will need to run nvm install node
- We also recommend you install [yarn][], which is an alternative to [npm][]

[MongoDB][] (v3.x+):

Mac (via [brew][]): brew tap mongodb/brew && brew install mongodb-community && brew services start mongodb-community.

Ubuntu:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 0C49F3730359A14518585931BC711F9BA15703C6
echo "deb http://repo.mongodb.org/apt/ubuntu "$(lsb_release -sc)"/mongodb-org/3.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.4.list
sudo apt-get update
sudo apt-get -y install mongodb-org

[Redis][] (v4.x+):

Mac (via [brew][]): brew install redis && brew services start redis

Ubuntu:

sudo add-apt-repository -y ppa:chris-lea/redis-server
sudo apt-get update
sudo apt-get -y install redis-server

Install

[npm][]:

npm install -g lad

[yarn][]:

yarn global add lad

Usage

Create a project

lad new-project
cd new-project

Development

To begin, try typing npm start (or yarn start) on command line. This will display to you all the scripts you can run.

The start script (among many others) uses [nps][] and [nps-utils][] under the hood. This helps to keep scripts very developer-friendly, and rids the need to write in JSON syntax.

This script accepts a <task> argument, whereas a task of all will spawn, watch, and re-compile all of the microservices mentioned above.

Just open http://localhost:3000 for testing!