MEAN Stack Starter Kit

MEANcore is an open-source boilerplate solution based on the MEAN stack and provides a solid starting point for MongoDB, Node.js, Express, and Angular based applications. This project includes modern tools and workflow based on angular-cli, best practices from the community, a scalable base template and a good learning base.

Benefits

Quickstart a project in seconds and focus on features, not on frameworks or tools
Industrial-grade tools, ready for usage in a continuous integration environment and DevOps
Scalable architecture with base app template including example components, services and tests
Module based development for both client and server

Before You Begin

Before you begin, it's recommend you read about the basic building blocks that assemble a MEAN stack application:

MongoDB - Go through MongoDB Official Website and proceed to their Official Manual, which should help you understand NoSQL and MongoDB better.
Express - The best way to understand express is through its Official Website, which has a Getting Started guide, as well as an ExpressJS guide for general express topics. You can also go through this StackOverflow Thread for more resources.
Angular - Angular's Official Website is a great starting point.
Node.js - Start by going through Node.js Official Website and this StackOverflow Thread, which should get you going with the Node.js platform in no time.

Checkout our blog Techievor built on meancore for a full rundown on how to setup the MEAN stack with MEANcore:

Prerequisites

Make sure you have installed all of the following prerequisites on your development machine:

Git - Download & Install Git. OSX and Linux machines typically have this already installed.
Node.js - Download & Install Node.js and the npm package manager. If you encounter any problems, you can also use this GitHub Gist to install Node.js. This version of MEANcore requires at minimum version >=14.0.0 of Node.js, v14.15.0 being the recommended.
MongoDB - Download & Install MongoDB, and make sure it's running on the default port (27017). This version of MEANcore requires at minimum version >=4.2, v4.2.15 being the recommended.

Getting Started

Go to project folder and create a .env file to setup your environment

NODE_ENV='development'
PRODUCTION=
HTTP_PROXY=

MONGO_SEED_LOG_RESULTS=true

GOOGLE_ANALYTICS_ID=''
GOOGLE_CLIENT_EMAIL=''
GOOGLE_PRIVATE_KEY=""
GOOGLE_VIEW_ID=
RECAPTCHA_SECRET_KEY=''
RECAPTCHA_SITE_KEY=''

MAILER_FROM='support@meancore.com'
MAILER_SERVICE_PROVIDER=
MAILER_HOST='smtp.ethereal.email'
MAILER_PORT=587
MAILER_USER='username'
MAILER_SECRET='pass'
MAILER_TEST=true

Setup link-package:

npm run init

This command will setup git hooks and preemptively bundle all package.json files located under the modules directory.

Next install dependencies:

npm install

Run the MongoDB Seed (Optional) To have the default menu feature(s), role(s), and/or user account(s) at runtime:

npm run seed

This will try to seed the features, roles, and users based on the defined NODE_ENV in your env config. You have to copy the user passwords from the console and store it somewhere safe.

Running with TLS (Optional) The application will start by default with the secuire configuration (SSL mode) turned off and listen on port 3000. To run your application in a secure manner, you'll need to use OpenSSL and generate a set of self-signed certificates. Unix-based users can use the following command:

npm run generate-ssl-certs

Windows users can follow the instructions found here. After you've generated the key and certificate, ensure they are placed in the config/sslcerts folder.

Then launch development server, and open localhost:4200 in your browser:

npm run start:dev

Running in Production

To run MEANcore with production environment settings, you must set the following env variables:

NODE_ENV='production'
PRODUCTION=true

To enable/disable SSL mode in a production environment, set the HOST_SECURE variable in your env config.

Explore config/env/production.js for additional production environment configuration options.

Project Structure

config/                      configuration for express
dist/                        compiled bundled client version
modules/**                   contains various modules that can be bundled together
|- client/                      project source code for client
|  |- app/                      app components
|  |  |- app.component.*        app root component (shell)
|  |  |- app.module.ts          app root module definition
|  |  |- app-routing.module.ts  app routes
|  |- assets/                   app assets (images, fonts, sounds...)
|  |- environments/             values for various build environments
|  |  features/                 additional modules and components
|  |- theme/                    app global scss variables and theme
|  |- index.html                html entry point
|  |- main.scss                 global style entry point
|  |- main.ts                   app entry point
|  |- polyfills.ts              polyfills needed by Angular
|  +- test.ts                   unit tests entry point
|- e2e/                         end-to-end tests
|- server/                      project source code for server
project/                         bundled client modules
shared_modules/              custom modules that are shared between the client and server
tools/                       scripts for configuration and managing the application
|- bundle-modules.js         bundles all module's client folder under project for ng build
|- bundle-packages.js        bundles all module's packages into a single file in project root
|- generate-sitemap.js       generates a sitemap.xml with all routes in project
|- generate-ssl-certs.sh     generate self-signed certs for dev testing
|- init-core.js              creates npm & git env vars for git hooks
|- link-packages.js          replaces npm install/uninstall to keep all module packages in sync
|- seed-db.js                seeds the db with default configuration based on config
|- set-env.ts                run to configure environment configuration based on process.env
|- unbundle-packages.js      reverse of bundle-packages
reports/                     test and coverage reports
.env                         process.env variable configuration
proxy.conf.js                backend proxy configuration
server.js                    script to launch express

Main Tasks

Task automation is based on NPM scripts.

Tasks	Description
npm run init	Creates npm & git environment variables for git hooks used for link-packages
npm run bundle:packages	Bundles all packages under modules directory into single file used by root
npm run unbundle:packages	Reverses bundle:packages
npm run link:install	Replaces npm install; used to keep linked module packages in sync
npm run link:uninstall	Replaces npm uninstall; used to keep linked module packages in sync
npm run bundle:modules	Bundles all module's client folder into project directory for ng build
npm run watch:dev	Watches each module client directory for changes and rebundles into project folder for ng to pick up
npm run build:dev	Lint code and build app for development in `dist/` folder
npm run build:prod	Lint code and build app for production in `dist/` folder
npm run client:dev	Run development ng server on `http://localhost:4200/` only
npm run server:dev	Run development express server only on `http://localhost:3000/`
npm run server:prod	Run production express server only
npm run start:dev	Builds client and runs development ng server on `http://localhost:4200/` using proxy config for express endpoints to `http://localhost:3000/`
npm run start:prod	Builds client for prod and runs production express server
npm run test:client	Lint code and run unit tests once for continuous integration
npm run lint:client	Lint client code
npm run lint:server	Lint server code
npm run e2e	Run e2e tests using Protractor
npm run generate-ssl-certs	Generates self-signed certificates on Unix-based systems using OpenSSL
npm run seed	Seeds the database with defaults based on defined configuration

Link Packages

The follow parameters are used with link:install & link:uninstall

parms:                     
  |--pkg={name of npm package} 
  |--type={type of dependency: blank or dependencies; dev or devDependencies} 
  |--mod={target mod; can leave blank for core}

Development Server

Run npm run start:dev for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files. You should not use ng serve directly, as it does not use the backend express configuration.

Code Scaffolding

Run npm run generate -- component <name> to generate a new component. You can also use npm run generate -- directive|pipe|service|class|module.

If you have installed angular-cli globally with npm install -g @angular/cli, you can also use the command ng generate directly.

Running Unit Tests

Run ng test to execute the unit tests via Karma.

Running End-to-End Tests

Run ng e2e to execute the end-to-end tests via Protractor.

Further Help

Tasks are mostly based on the angular-cli tool. Use ng help to get more help or go check out the Angular-CLI README.

What's In The Box

The app template is based on HTML5, TypeScript and Sass.

Tools

Development, build and quality processes are based on angular-cli and NPM scripts, which includes:

Optimized build and bundling process with Webpack
Cross-browser CSS with autoprefixer and browserslist
Asset revisioning for better cache management
Server-side rendering for web-crawlers using Puppeteer
Unit tests using Jasmine and Karma
End-to-end tests using Protractor
Static code analysis: ESLint, Angular-ESLint, Stylelint and HTMLHint

Libraries

Contributing

Pull requests are welcome from the community! Just be sure to read the contributing doc to get started.

Credits

Special thanks to the MEAN.JS team for the hard work they put into their project. I used their base for many projects over the years and learned a lot from what they accomplished.

mrdav30 / MEANcore