{"id":13527345,"url":"https://github.com/marmelab/javascript-boilerplate","last_synced_at":"2025-10-08T02:31:48.127Z","repository":{"id":66330463,"uuid":"49864754","full_name":"marmelab/javascript-boilerplate","owner":"marmelab","description":"Node.js+Koa.js+PostgreSQL+React.js+Webpack+Mocha+Makefile, a starter kit for new apps","archived":true,"fork":false,"pushed_at":"2019-04-17T15:01:22.000Z","size":1035,"stargazers_count":251,"open_issues_count":9,"forks_count":54,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-10-03T05:48:56.459Z","etag":null,"topics":["boilerplate","koa","postgresql","react","redux"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marmelab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-01-18T09:05:11.000Z","updated_at":"2024-04-02T09:51:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"c8d26b0f-3cbb-4ebd-8c9b-2ed6356b849b","html_url":"https://github.com/marmelab/javascript-boilerplate","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/marmelab/javascript-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmelab%2Fjavascript-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmelab%2Fjavascript-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmelab%2Fjavascript-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmelab%2Fjavascript-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marmelab","download_url":"https://codeload.github.com/marmelab/javascript-boilerplate/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmelab%2Fjavascript-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278877647,"owners_count":26061489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boilerplate","koa","postgresql","react","redux"],"created_at":"2024-08-01T06:01:46.169Z","updated_at":"2025-10-08T02:31:47.777Z","avatar_url":"https://github.com/marmelab.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003ctable\u003e\n        \u003ctr\u003e\n            \u003ctd\u003e\u003cimg width=\"20\" src=\"https://cdnjs.cloudflare.com/ajax/libs/octicons/8.5.0/svg/archive.svg\" alt=\"archived\" /\u003e\u003c/td\u003e\n            \u003ctd\u003e\u003cstrong\u003eArchived Repository\u003c/strong\u003e\u003cbr /\u003e\n            This code is no longer maintained. Feel free to fork it, but use it at your own risks.\n        \u003c/td\u003e\n        \u003c/tr\u003e\n\u003c/table\u003e\n\n# marmelab-boilerplate [![Build Status](https://travis-ci.org/marmelab/javascript-boilerplate.svg?branch=master)](https://travis-ci.org/marmelab/javascript-boilerplate)\n\nA starter kit for new apps, based on:\n\n* ES6 everywhere (with some bits of ES7, e.g. spread operator on objects)\n* React.js, React Router, and Redux (for the frontend)\n* Admin-on-rest (for the admin)\n* Node.js, Koa.js and PostgreSQL (for the API server)\n* Makefile, webpack and Mocha (for the build and test)\n\nFeatures:\n\n* Babel transpilation (es2015, react, stage-0) for both client and server code\n* Node.js API built on top of Koa.js (successor of Express) for cleaner async code\n* Automated CRUD resources based on a PostgreSQL database (using `pg` and `co-postgres-queries`)\n* State-of the art robustness and security for the API (JWT, rate limiting, secure headers, based on `helmet`)\n* Separated API for the admin, with different security settings (and login form)\n* Built-in database migration handling (using `db-migrate`)\n* Production-level logging (using `winston`)\n* CORS support (including on IE8, thanks to `xDomain`)\n* Fully automated start and stop (see `Makefile`)\n* Auto-reload of Node.js code upon modification (using `pm2`)\n* Frontend app built with React, `redux`, `redux-saga`, `react-router`, and `redux-form`\n* Using `react-dev-tools` and hot reload for easier development\n* SASS preprocessor (using `node-sass`)\n* Including a non-trivial example with several routes, Ajax calls, and functional tests\n* Fully automated build with `webpack`, including development (`webpack-dev-server`) and production target (minified)\n* Admin app built with React.js and `admin-on-rest`\n* Including a full-featured admin panel with references\n* Unified test build, running unit and functional tests on all apps, powered by `mocha` and `selenium`\n* AWS deployment automated by Fabric\n* Sensible `eslint` defaults, based on Airbnb's rules\n\nThe boilerplate contains a sample app with three domains: users, products, and orders. Feel free to remove the corresponding files once you start implementing your own domain.\n\n## Install\n\nRequirements:\n\n* Node.js V5\n* PostgreSQL\n* openjdk-8-jre (to install selenium-standalone)\n\n```sh\n# install npm dependencies and Selenium (for tests)\nmake install\n```\n\n**Tip**: Add `alias make='make -s'` to your bash profile (bashrc, zshrc) for a better display.\n\n## Understand\n\nThe project directory structure is as follows:\n\n![architecture](doc/api-centric-architecture.png)\n\n```\nbin/ # CLI tasks\nbuild/ # compiled JS and CSS files for the admin and frontend app. The web root in production.\nconfig/ # Project configuration\ndoc/\ne2e/ # Functional tests\nsrc/\n  api/ # The server API code (Node.js, Koa.js)\n  admin/ # The admin dashboard code (Angular.js, ng-admin)\n  frontend/ # The frontend code (React.js, Redux)\n  isomorphic/ # Code common to several apps\nwebpack/ # Webpack configuration (for admin and frontend compilation)\n```\n\nThe entire code (api, admin, and frontend) is written in ES6 and transpiled to ES5 by babel.\n\n**Tip**: In production, the compiled JS and CSS files (under `build/`) are served by the Node.js server. In development, it's done by webpack-dev-server.\n\nThe main entry point for understanding the code is probably `src/api/index.js`.\n\n## Project Configuration\n\nThis projects supports various runtime environments. This means that you can switch to an entirely different configuration based on the `NODE_ENV` environment variable:\n\n```sh\n# run the API server in development mode (default)\n$ node ./src/api/index.js\n# run the API server in test mode\n$ NODE_ENV=test node ./src/api/index.js\n# run the API server in production mode\n$ NODE_ENV=production node ./src/api/index.js\n```\n\n**Tip**: On the production servers, you should set the `NODE_ENV` variable using supervisor.\n\nIt uses [node-config](https://github.com/lorenwest/node-config) to let you configure the project for the development, test, and production environments. `node-config` supports configuration cascade, so the actual configuration for a given environment is the combination of `config/default.js` and `config/[NODE_ENV].js` (the configuration settings for a given environment override the default settings).\n\nBefore running the app in development, you must copy the `config/development-dist.js` into `config/development.js` (this is done by the `make install` command), and edit the server and database settings to your development environment. Same for the `test-dist.js` if you intend to run unit tests.\n\n**Note**: You need to remove all the demo code before to start your project. A [pull request is in progress](https://github.com/marmelab/javascript-boilerplate/pull/22) to do so, but this will take some time to finish it. Meanwhile, take a look on these folders to manually clean the code:\n- [src/api](src/api)\n- [src/frontend](src/frontend)\n- [src/admin](src/admin)\n- [src/api/e2e](src/api/e2e)\n- [src/frontend/e2e](src/frontend/e2e)\n\n## Develop\n\nThis project uses [pm2](https://github.com/Unitech/pm2) to manage its processes. Configuration files for pm2 can be found in the `./config/pm2_servers/` directory.\n\n```sh\n# start servers (node and webpack via pm2)\nmake run-dev\n# both servers will run in the background\n# the Node server uses nodemon and will restart on code change\n# the frontend is served by webpack dev server with hot reload\n\n# you can restart either the api or the frontend by hand\nmake restart-api\nmake restart-frontend\n```\n\nBrowse the app:\n\n* [http://localhost:8081](http://localhost:8081) for the admin app\n* [http://localhost:8080](http://localhost:8080) for the frontend app\n* [http://localhost:3000](http://localhost:3000) for the API\n\n**Tip**: You can change the API port by running `NODE_PORT=3001 make run-dev`. Or, for persistent change, you can add this environment variable into the [PM2 configuration file](config/pm2_servers/dev.json).\n\n```sh\n# stop servers (node and webpack)\nmake stop-dev\n```\n\n## Test\n\n```sh\n# tests run in the \"test\" environment and don't empty the \"development\" database\nmake test\n\n# alternatively, you can run any of the individual test suites:\nmake test-api-unit\nmake test-api-functional\nmake test-frontend-unit\nmake test-frontend-functional\nmake test-isomorphic-unit\n```\n\nAPI (and common lib) unit tests using:\n\n* [Mocha](http://mochajs.org/)\n* expect from [expect](https://github.com/mjackson/expect)\n\nAPI functional tests using:\n\n* [Mocha](http://mochajs.org/)\n* expect from [expect](https://github.com/mjackson/expect)\n* [request](https://github.com/request/request)\n\nFrontend unit tests using:\n\n* [Mocha](http://mochajs.org/)\n* expect from [expect](https://github.com/mjackson/expect)\n* [Redux Thunk](https://github.com/gaearon/redux-thunk), [redux-mock-store](https://github.com/arnaudbenard/redux-mock-store) and [nock](https://github.com/pgte/nock)\nto test redux action creators (as explain in [redux documentation](http://rackt.org/redux/docs/recipes/WritingTests.html))\n* [enzyme](https://github.com/airbnb/enzyme) to test react components\n\nFrontend fonctional tests using:\n\n* [selenium-webdriver](https://github.com/SeleniumHQ/selenium)\n\n\n## Deployment\n\nSee [deployment instructions](doc/DEPLOY.md).\n\n\n## Managing servers with PM2\n\ndev and tests servers are managed with PM2. So, It's possible to :\n\n```sh\n# display the 'front dev' server's logs\nmake log-frontend-dev\n# display the 'api dev' server's logs\nmake log-api-dev\n\n# display the list of all servers\nmake servers-list\n# display the monitoring for all servers\nmake servers-monitoring\n# stop all servers\nmake servers-stop-all\n# stop all servers, delete them, and clear their logs.\nmake servers-clear-all\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarmelab%2Fjavascript-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarmelab%2Fjavascript-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarmelab%2Fjavascript-boilerplate/lists"}