Lad is the best Node.js framework. Made by a former Express TC and Koa team member.
Lad boasts dozens of features and is extremely configurable.
These microservices are preconfigured for security, performance, and graceful reloading.
Finally a framework that solves i18n everywhere; complete with automatic translation.
Our beautiful email engine uses email-templates (which is also made by the creator of Lad)!
We've spent a lot of time designing a beautiful error handler.
text/html, application/json, and text response typesSee koa-better-error-handler for a complete reference.
We strictly support Mac and Ubuntu-based operating systems (Windows might work).
Please ensure your operating system has the following software installed:
Git - see GitHub's tutorial for installation
MongoDB (v3.x+):
Mac (via brew): brew install mongodb && brew services start mongo
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
npm:
npm install -g lad
yarn:
yarn global add lad
lad new-project
cd new-project
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!
npm:
npm start all
yarn:
yarn start all
DEBUG - debug using debug output (widely adopted package in the community for debugging across all Node packages):
DEBUG=* ...
NODE_DEBUG - debug node internal modules:
NODE_DEBUG=* ...
MONGOOSE_DEBUG - debug Mongoose raw database operation output:
MONGOOSE_DEBUG=true ...
TRANSPORT_DEBUG - debug Nodemailer transport:
TRANSPORT_DEBUG=true ...
REDIS_MONITOR - debug Redis using MONITOR (uses @ladjs/redis and passes true for the monitor argument):
REDIS_MONITOR=true ...
REDIS_FRIENDLY_ERROR_STACK - debug Redis with friendly error stack messages (see showFriendlyErrorStack option of ioredis)
REDIS_FRIENDLY_ERROR_STACK=true ...
We strongly recommend using SemaphoreCI, PM2, and Digital Ocean for production deployment.
We've provided you with a preconfigured ecosystem.json deployment file. You will need to modify this file with your server's IP, hostname, and other metadata if needed.
Make sure that your project's assets are built with NODE_ENV=production flag, e.g. NODE_ENV=production npm run build (or with yarn as yarn build);this creates a build/rev-manifest.json file per koa-manifest-rev.
You can test this locally by installing PM2 globally with npm or yarn, and then running the following command:
NODE_ENV=production pm2 start
See the Continuous Integration and Code Coverage and Tutorials sections below for instructions on how to setup continuous integration, code coverage, and deployment.
If you specify an environment variable value for AWS_CF_DOMAIN and NODE_ENV=production is set then your assets will need to be published to Amazon S3/Cloudfront. To do so run npm start publish-assets (or with yarn as yarn start publish-assets). This command automatically sets NODE_ENV=production for you as well via cross-env.
We use ava and nyc for testing and code coverage.
npm:
npm test
yarn:
yarn test
We have made configuration of your Lad project easy through a dotenv configuration package called @ladjs/env, per Twelve-Factor.
We use the following three packages to manage configuration:
.env definition (otherwise known as a "schema") in a file named .env.schema.env and .env.defaults configuration filesprocess.env (e.g. FOO=4 will set process.env.FOO = 4 with a Number variable type instead of a String)Configuration is managed by the following, in order of priority:
config/index.js (reads in process.env environment variables)config/environments/ (sets defaults per environment, e.g. you can pass NODE_ENV=staging and it will load the file at config/environments/staging.js)NODE_ENV=production).env.env.defaultsPrecedence is taken by the environment configuration files, environment variables, then the .env file.
Basically dotenv won't set an environment variable if it already detects it was passed as an environment variable.
Take a look at the config folder contents and also at the defaults at .env.defaults.
NODE_ENV - (options: development, production default: development) - the node environment the app is running inPROXY_PORT - (default: 8080) - proxy port used to proxy requests (see ladjs/proxy)HTTP_PROTOCOL - (defaults: http recommend: https) - protocol used for http requestsHTTP_PORT - (defaults: 80 recommend: 443) - http port used for http requestsWEB_PROTOCOL - (default: http) - ladjs/web application protocolWEB_HOST - (default: localhost) - ladjs/web application hostWEB_PORT - (default: 3000) - ladjs/web application portWEB_URL - (default: {{WEB_PROTOCOL}}://{{WEB_HOST}}:{{WEB_PORT}}) - web application absolute URIWEB_SSL_KEY_PATH - ladjs/web file path to your SSL key fileWEB_SSL_CERT_PATH - ladjs/web file path to your SSL certificate fileWEB_SSL_CA_PATH - ladjs/web file path to your SSL certificate authority fileAPI_HOST - (default: localhost) - ladjs/api hostAPI_PORT - (default: 4000) - ladjs/api portAPI_PROTOCOL - (default: http recommend: https) - ladjs/api protocolAPI_URL - (default: {{API_PROTOCOL}}://{{API_HOST}}:{{API_PORT}}) - ladjs/api absolute URIAPI_SSL_KEY_PATH - ladjs/api file path to your SSL key fileAPI_SSL_CERT_PATH - ladjs/api file path to your SSL certificate fileAPI_SSL_CA_PATH - ladjs/api file path to your SSL certificate authority fileAPI_RATELIMIT_WHITELIST - ladjs/api ratelimiter whitelisted ips (see: koa-simple-ratelimit)APP_NAME - (default: Lad) - application name (see usage)APP_COLOR - application color theme (see usage)TWITTER - (default: @niftylettuce) twitter handleSEND_EMAIL - (default: false) - whether to send email or preview (see outbound email configuration)TRANSPORT_DEBUG - (default: false) - email transport debug logging (see debugging)EMAIL_DEFAULT_FROM - (default: support@127.0.01) - default email from addressSHOW_STACK - (default: true) - whether or not to output a stack trace when logging (see cabinjs options)SHOW_META - (default: true) - whether or not to output metadata to logger methods (see cabinjs options)SUPPORT_REQUEST_MAX_LENGTH - (default: 500) - support request max message size in charactersERROR_HANDLER_BASE_URL - (default: {{WEB_URL}}) error handling base url (see koa-better-error-handler)I18N_SYNC_FILES - (default: true) - sync locale information across all files (see ladjs/i18n options)I18N_AUTO_RELOAD - (default: false) - watch for changes in json files to reload locale on updates (see ladjs/i18n options)I18N_UPDATE_FILES - (default: true) - write new locale information to disk (see ladjs/i18n options)AUTH_LOCAL_ENABLED - (default: true) - enable passport local strategy (see ladjs/passport)AUTH_FACEBOOK_ENABLED - (default: false) - enable authenticating with Facebook using the OAuth 2.0 (see ladjs/passport)AUTH_TWITTER_ENABLED - (default: false) - enable authenticating with Twitter using the OAuth 1.0 (see ladjs/passport)AUTH_GOOGLE_ENABLED - (default: false) - enable authenticating with Google using OAuth 2.0 (see google auth)AUTH_GITHUB_ENABLED - (default: false) - enable authenticating with Github using OAuth 2.0 (see ladjs/passport)AUTH_LINKEDIN_ENABLED - (default: false) - enable authenticating with LinkedIn using OAuth 1.0 (see ladjs/passport)AUTH_INSTAGRAM_ENABLED - (default: false) - enable authenticating with Instagram using OAuth 2.0 (see ladjs/passport)AUTH_OTP_ENABLED - (default: false) - enable authenticating with OTP, a form of two-factor authentication (see ladjs/passport)AUTH_STRIPE_ENABLED - (default: false) - enable authenticating with Stripe using OAuth 2.0 (see ladjs/passport)GOOGLE_CLIENT_ID - google oauth2 client id (see google auth)GOOGLE_CLIENT_SECRET - google oauth2 secret (see google auth)GOOGLE_CALLBACK_URL - google oauth2 callback url (see google auth)GOOGLE_APPLICATION_CREDENTIALS - path to google cloud platform credentials (see gcp credentials)GITHUB_CLIENT_ID - github oauth client id (see ladjs/passport)GITHUB_CLIENT_SECRET - github oauth secret (see ladjs/passport)GITHUB_CALLBACK_URL - github oauth callback URL (see ladjs/passport)POSTMARK_API_TOKEN - postmark api token (see outbound email configuration)CODECOV_TOKEN - codecov api token (see continuous integration and code coverage)MONGO_USER - mongodb usernameMONGO_PASS - mongodb passwordMONGO_HOST - (default: localhost) - mongodb hostnameMONGO_PORT - (default: 27017) - mongodb portMONGO_NAME - (default: {{APP_NAME}}_{{NODE_ENV}}) - mongodb nameMONGO_URI - (default: mongodb://{{MONGO_HOST}}:{{MONGO_PORT}}/{{MONGO_NAME}}) - mongodb connection URIWEB_MONGO_USER - ladjs/web mongodb usernameWEB_MONGO_PASS - ladjs/web mongodb passwordWEB_MONGO_HOST - ladjs/web mongodb hostnameWEB_MONGO_NAME - ladjs/web mongodb nameWEB_MONGO_PORT - ladjs/web mongodb portWEB_MONGO_URI - ladjs/web mongodb connection URIAPI_MONGO_USER - ladjs/api mongodb usernameAPI_MONGO_PASS - ladjs/api mongodb passwordAPI_MONGO_HOST - ladjs/api mongodb hostnameAPI_MONGO_NAME - ladjs/api mongodb nameAPI_MONGO_PORT - ladjs/api mongodb portAPI_MONGO_URI - ladjs/api mongodb connection URIBREE_MONGO_USER - breejs/bree mongodb usernameBREE_MONGO_PASS - breejs/bree mongodb passwordBREE_MONGO_HOST - breejs/bree mongodb hostnameBREE_MONGO_NAME - breejs/bree mongodb nameBREE_MONGO_PORT - breejs/bree mongodb portBREE_MONGO_URI - breejs/bree mongodb connection URIREDIS_PORT - (default: 6379) - redis portREDIS_HOST - (default: localhost) - redis hostnameREDIS_PASSWORD - redis passwordWEB_REDIS_PORT - ladjs/web redis portWEB_REDIS_HOST - ladjs/web redis hostnameWEB_REDIS_PASSWORD - ladjs/web redis passwordAPI_REDIS_PORT - ladjs/api redis portAPI_REDIS_HOST - ladjs/api redis hostnameAPI_REDIS_PASSWORD - ladjs/api redis passwordBREE_REDIS_PORT - breejs/bree redis portBREE_REDIS_HOST - breejs/bree redis hostnameBREE_REDIS_PASSWORD - breejs/bree redis passwordMANDARIN_REDIS_PORT - mandarin redis portMANDARIN_REDIS_HOST - mandarin redis hostnameMANDARIN_REDIS_PASSWORD - mandarin redis passwordCERTBOT_WELL_KNOWN_NAME - letsencrypt wellknown name (see certbot options)CERTBOT_WELL_KNOWN_CONTENTS - letsencrypt wellknown contents (see certbot options)VERIFICATION_PIN_TIMEOUT_MS - (default: 5m) - email verification pin expiryVERIFICATION_PIN_EMAIL_INTERVAL_MS - (default: 1m) - email verification pin email intervalAPI_SECRETS - (default: secret) - list of restricted api secretsCACHE_RESPONSES - (default: false) - cache specified responses (see ladjs/koa-cache-responses)SLACK_API_TOKEN - slack api token (see slack web api)To configure SSL for the web or API server simply set them in your .env file or pass them as environment variables.
Web server:
WEB_PROTOCOL - you must set this to httpsWEB_SSL_KEY_PATH - file path to your SSL key file (e.g. /home/deploy/.ssl/web-key.pem)WEB_SSL_CERT_PATH - file path to your SSL certificate file (e.g. /home/deploy/.ssl/web-cert.pem)WEB_SSL_CA_PATH (optional) - file path to your SSL certificate authority file (e.g. /home/deploy/.ssl/web-ca-cert.pem)API server:
API_PROTOCOL - you must set this to httpsAPI_SSL_KEY_PATH - file path to your SSL key file (e.g. /home/deploy/.ssl/api-key.pem)API_SSL_CERT_PATH - file path to your SSL certificate file (e.g. /home/deploy/.ssl/api-cert.pem)API_SSL_CA_PATH (optional) - file path to your SSL certificate authority file (e.g. /home/deploy/.ssl/api-ca-cert.pem)By default in the development environment we simply render the email in your browser.
However in other environments such as production, you definitely want emails to be sent.
We built-in support for Postmark by default (though you can swap in your own transport provider in the jobs/email.js file):
Go to https://postmarkapp.com – Start Free Trial
Create a free trial account, then click Get Started, and proceed to create a "Server" and "Sender Signature"
Copy/paste the "Server API token" under "Credentials" in your .env file (example below)
-POSTMARK_API_TOKEN=
+POSTMARK_API_TOKEN=ac6657eb-2732-4cfd-915b-912b1b10beb1
Modify the SEND_EMAIL variable in .env from false to true
You can customize the favicon and touch icons – just generate a new set at https://realfavicongenerator.net and overwrite the existing in the assets folder.
Just make sure that any relative paths match up in the assets/browserconfig.xml and assets/manifest.json files.
We use Lad's auth package under the hood; so if you want to configure authentication providers you'll want to read more or contribute to @ladjs/auth.
In order to add Google sign-in to your app (so users can log in with their Google account):
Go to https://console.developers.google.com – Create a project (and fill out your project information – if you need a 120x120px default image, you can use this one with a CDN path of https://cdn.rawgit.com/ladjs/lad/82d38d64/media/lad-120x120.png
Under your newly created project, go to Credentials – Create credentials – OAuth client ID – Web application
Set "Authorized JavaScript origins" to http://yourdomain.com (replace with your domain) and also http://localhost:3000 (for local development)
Set "Authorized redirect URIs" to http://yourdomain.com/auth/google/ok (again, replace with your domain) and also http://localhost:3000/auth/google/ok (again, for local development)
Copy and paste the newly created key pair for respective properties in your .env file (example below)
-GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_ID=424623312719-73vn8vb4tmh8nht96q7vdbn3mc9pd63a.apps.googleusercontent.com
-GOOGLE_CLIENT_SECRET=
+GOOGLE_CLIENT_SECRET=Oys6WrHleTOksqXTbEY_yi07
In .env, make sure that AUTH_GOOGLE_ENABLED=true to enable this authentication method.
GOOGLE_TRANSLATE_KEY=******We strongly recommend that you use SemaphoreCI for continuous integration and Codecov for code coverage.
Here are the simple steps required to setup SemaphoreCI with Codecov:
Go to SemaphoreCI and sign up for a free account
Once your repository is pushed to GitHub, add it as a project on SemaphoreCI
Configure your project on SemaphoreCI with the following build settings:
Replace
npmwithyarnif you're using yarn as your package manager
JavaScript10+ (latest LTS)
Note you can also add to
Setupthe scriptnvm install latestto install latest version if SemaphoreCI does not provide it from the drop-down
npm installnpm run test-coveragenpm run coverageGo to Codecov and sign up for a free account
Add your project on Codecov and copy to your clipboard the token
Go to SemaphoreCI's Project Settings for your project and add CODECOV_TOKEN as an environment variable (with the contents from your clipboard)
Run a test build ("Rebuild last revision") on SemaphoreCI and check to make sure your code coverage report uploads properly on Codecov
Ensure your README.md file has the build status and code coverage badges rendered properly (you will need to use a different badge link from each provider if your GitHub repository is private)
In order for your assets to get properly served in a production environment, you'll need to configure AWS:
Go to https://console.aws.amazon.com/iam/home#security_credential ‐ Access Keys – Create New Access Key
Copy and paste the newly created key pair for respective properties in your .env file (example below)
-AWS_IAM_KEY=
+AWS_IAM_KEY=AKIAJMH22P6W674YFC7Q
-AWS_IAM_SECRET=
+AWS_IAM_SECRET=9MpR1FOXwPEtPlrlU5WbHjnz2KDcKWSUcB+C5CpS
Enable your API by clicking on Overview and then clicking the Enable button
Go to https://console.aws.amazon.com/s3/home – Create Bucket
Create a bucket and copy/paste its name for the property in .env (example below)
-AWS_S3_BUCKET=
+AWS_S3_BUCKET=lad-development
Go to https://console.aws.amazon.com/cloudfront/home – Create Distribution – Get Started
Set "Origin Domain Name" equal to your S3 bucket name (their autocomplete drop-down will help you find it)
Leave the remaining defaults as is (some fields might be blank, this is OK)
Copy/paste the newly created Distribution ID and Domain Name for respective properties in your .env file (example below)
-AWS_CF_DI=
+AWS_CF_DI=E2IBEULE9QOPVE
-AWS_CF_DOMAIN=
+AWS_CF_DOMAIN=d36aditw73gdrz.cloudfront.net
The following bash output is the directory structure and organization of Lad:
tree template -I "build|node_modules|coverage|test"
template
├── LICENSE
├── README
├── api.js
├── app
│ ├── controllers
│ │ ├── api
│ │ │ ├── index.js
│ │ │ └── v1
│ │ │ ├── index.js
│ │ │ ├── log.js
│ │ │ └── users.js
│ │ ├── index.js
│ │ └── web
│ │ ├── admin
│ │ │ ├── index.js
│ │ │ └── users.js
│ │ ├── auth.js
│ │ ├── index.js
│ │ ├── my-account.js
│ │ └── support.js
│ ├── models
│ │ ├── index.js
│ │ ├── inquiry.js
│ │ └── user.js
│ └── views
│ ├── 404.pug
│ ├── 500.pug
│ ├── _breadcrumbs.pug
│ ├── _footer.pug
│ ├── _nav.pug
│ ├── _pagination.pug
│ ├── _register-or-login.pug
│ ├── about.pug
│ ├── admin
│ │ ├── index.pug
│ │ └── users
│ │ ├── index.pug
│ │ └── retrieve.pug
│ ├── dashboard
│ │ └── index.pug
│ ├── forgot-password.pug
│ ├── home.pug
│ ├── layout.pug
│ ├── my-account
│ │ ├── index.pug
│ │ └── security.pug
│ ├── privacy.pug
│ ├── register-or-login.pug
│ ├── reset-password.pug
│ ├── spinner
│ │ ├── 1.pug
│ │ ├── 10.pug
│ │ ├── 11.pug
│ │ ├── 2.pug
│ │ ├── 3.pug
│ │ ├── 4.pug
│ │ ├── 5.pug
│ │ ├── 6.pug
│ │ ├── 7.pug
│ │ ├── 8.pug
│ │ ├── 9.pug
│ │ └── spinner.pug
│ ├── support.pug
│ └── terms.pug
├── assets
│ ├── browserconfig.xml
│ ├── css
│ │ ├── _custom.scss
│ │ ├── _email.scss
│ │ ├── _hljs.scss
│ │ ├── _sticky-footer.scss
│ │ ├── _variables.scss
│ │ └── app.scss
│ ├── fonts
│ ├── img
│ │ ├── android-chrome-192x192.png
│ │ ├── android-chrome-384x384.png
│ │ ├── apple-touch-icon.png
│ │ ├── favicon-16x16.png
│ │ ├── favicon-32x32.png
│ │ ├── favicon.ico
│ │ ├── logo-square.svg
│ │ ├── mstile-150x150.png
│ │ ├── social.png
│ │ └── twitter.png
│ ├── js
│ │ ├── core.js
│ │ ├── logger.js
│ │ └── uncaught.js
│ ├── manifest.json
│ └── robots.txt
├── bull.js
├── config
│ ├── env.js
│ ├── index.js
│ ├── meta.js
│ ├── phrases.js
│ ├── polyfills.js
│ └── utilities.js
├── ecosystem.json
├── emails
│ ├── _content.pug
│ ├── _footer.pug
│ ├── _nav.pug
│ ├── inquiry
│ │ ├── html.pug
│ │ └── subject.pug
│ ├── layout.pug
│ ├── reset-password
│ │ ├── html.pug
│ │ └── subject.pug
│ └── welcome
│ ├── html.pug
│ └── subject.pug
├── env
├── gitignore
├── gulpfile.js
├── helpers
│ ├── i18n.js
│ ├── index.js
│ ├── logger.js
│ ├── passport.js
│ └── policies.js
├── index.js
├── locales
│ ├── en.json
│ ├── es.json
│ └── zh.json
├── nodemon.json
├── package-scripts.js
├── package.json
├── proxy.js
├── queues
│ ├── email.js
│ ├── index.js
│ └── mandarin.js
├── routes
│ ├── api
│ │ ├── index.js
│ │ └── v1
│ │ └── index.js
│ ├── index.js
│ └── web
│ ├── admin.js
│ ├── auth.js
│ ├── index.js
│ └── my-account.js
├── template
├── web.js
└── yarn.lock
31 directories, 119 files
Lad is designed according to these principles:
Interesting in contributing to this project or testing early releases?
Follow all of the above Requirements
You will need to fork and clone this repository locally
After forking, follow these steps:
cd lad
yarn install
cd template
yarn install
yarn start
If you'd like to preview changes to the README.md file, you can use docute.
yarn global add docute-cli
cd lad
docute ./
Then visit http://localhost:8080 in your browser.
| Name | Website |
|---|---|
| Nick Baugh | http://niftylettuce.com |
| Shaun Warman | https://shaunwarman.com/ |
Lad, Lass, Cabin, Lipo, and their respective logos are trademarks of Niftylettuce LLC. These trademarks may not be reproduced, distributed, transmitted, or otherwise used, except with the prior written permission of Niftylettuce LLC. If you are seeking permission to use these trademarks, then please contact us.
FAQs
Lad is the best Node.js framework. Made by a former Express TC and Koa team member.
The npm package lad receives a total of 39 weekly downloads. As such, lad popularity was classified as not popular.
We found that lad demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.
Research
Security News
Socket researchers uncovered a malicious PyPI package exploiting Deezer’s API to enable coordinated music piracy through API abuse and C2 server control.
Research
The Socket Research Team discovered a malicious npm package, '@ton-wallet/create', stealing cryptocurrency wallet keys from developers and users in the TON ecosystem.