{"id":13786046,"url":"https://github.com/maxime1992/angular-ngrx-starter","last_synced_at":"2025-09-03T17:09:33.648Z","repository":{"id":87594525,"uuid":"91131403","full_name":"maxime1992/angular-ngrx-starter","owner":"maxime1992","description":"An opiniated Angular setup based on @angular/cli to kickstart an ngrx project","archived":false,"fork":false,"pushed_at":"2018-03-25T13:00:55.000Z","size":979,"stargazers_count":66,"open_issues_count":2,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-11T22:37:22.862Z","etag":null,"topics":["angular","angular-material-2","ngrx","ngrx-effects","ngrx-entity","ngrx-store","store-devtools"],"latest_commit_sha":null,"homepage":"https://maxime1992.github.io/angular-ngrx-starter/","language":"TypeScript","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/maxime1992.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-12T21:35:17.000Z","updated_at":"2025-03-20T11:03:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"c64ebb45-170b-4aab-8e45-614144c16e4c","html_url":"https://github.com/maxime1992/angular-ngrx-starter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/maxime1992/angular-ngrx-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxime1992%2Fangular-ngrx-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxime1992%2Fangular-ngrx-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxime1992%2Fangular-ngrx-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxime1992%2Fangular-ngrx-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxime1992","download_url":"https://codeload.github.com/maxime1992/angular-ngrx-starter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxime1992%2Fangular-ngrx-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273477148,"owners_count":25112621,"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-09-03T02:00:09.631Z","response_time":76,"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":["angular","angular-material-2","ngrx","ngrx-effects","ngrx-entity","ngrx-store","store-devtools"],"created_at":"2024-08-03T19:01:08.608Z","updated_at":"2025-09-03T17:09:33.585Z","avatar_url":"https://github.com/maxime1992.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Angular Ngrx Starter\n\n[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n\n*An opiniated Angular setup based on @angular/cli*\n\n[Angular-Cli](https://github.com/angular/angular-cli) can help you start an Angular project very quickly.\n\nBut when you need a lot of external modules/libs and you've got to setup everything, everytime, it can be quite long and repetitive.\n\n**This setup has the following modules already installed and configured :**  \n- Angular Material  \n- Material Design Icons  \n- Ng2 Translate  \n- Ngrx  \n  - Store  \n  - Effects  \n  - StoreDevtools\n\n![Image of the starter after ng serve](https://user-images.githubusercontent.com/4950209/28744765-23ffcfce-7468-11e7-8ace-1af8127a6926.png)\n\nIf you don't know angular-cli, please read the doc.\n\nI added one command to build the project as small as possible for production : `yarn run prod`.\n\nIf you're new to ngrx [store | effects], it might help you get started.\nI've put a lot of comments and a folder called \"pizzas\" for demo/scaffolding.\n\nDon't forget to install and take a look to [Redux DevTools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd) for state debugging.\n\n## Note on service-worker\nThe starter is pre-configured to generate a service-worker (thanks to angular-cli) and the only thing you need to do if you want your app to work offline, is to set `serviceWorker` to `true` in `.angular-cli.json`.\n\n## Note on unit testing\nThe starter is pre-configured to use Chromium in headless mode. If you want to change that behavior, you can simply pass the browser of your choice in `karma.conf.js`, property `browsers`.\n\n\u003chr\u003e\n\n# Lint, format and IDE setup\n## Prettier\nBefore we start digging into the architecture of this project, you have to know that *[Prettier](https://github.com/prettier/prettier)* is already setup and thus, you can format all your `.ts` and `.scss` by simply running `yarn run prettier:fix`. If you have a CI setup, you might want to run `yarn run prettier:check` to make sure every file is correctly formatted.\n\nAlso, a pre-commit hook has been setup and before you commit something, it'll check if all the file are well formatted. If you want to disable that behavior, remove `.git/hooks/pre-commit` and also the `precommit` key in `package.json`.\n\n## Visual Studio Code\nOf course, you can use your favorite editor/IDE. If you decide to use VSC, you might want to install [Angular Language Service](https://marketplace.visualstudio.com/items?itemName=Angular.ng-template). It'll give you autocompletion and type checking into your HTML templates.\n\n\u003chr\u003e\n\nWhat you need to know to start with this template :  \n*(all the code contains a lot of comments, so while reading the differents parts of this readme, I invite you to look the according files)*.\n\n# Styles\n## /src/styles.scss\nThis is just the main `scss` file where we can import the barrel from `/src/styles`. Indeed, the goal here is to avoid listing all our `scss` files into `/.angular-cli.json`, in `apps.styles`.\n\n## /src/styles/_index.scss\nThis is the main `scss` barrel. In the styles folder, you might want to create other folders. If you do so, create a barrel `/src/styles/themes/_themes.scss` where you import all the themes you need.\n\n## /src/styles/shared\nPut everything not related to a given component, that you may want to share across your app.\n\n### /src/styles/shared/_colors.scss\nThanks to material, you can define here your primary and accent colors. I've also added a `$color-palette` which might be useful if you need other colors. You'll see why in next section.\n\n### /src/styles/shared/_utils.scss\nSome utility classes. The main thing to notice here is the `@mixin generate-colors`. For every color you've listed in the `$color-palette`, it will generate the following css classes :  \n`color-#{$name}-x#{$index}`, `background-color-#{$name}-x#{$index}`, `border-color-#{$name}-x#{$index}` and `background-color-hover-#{$name}-x#{$index}:hover`. This way in your templates you can for example give a color to some text like that : `\u003cp class=\"color-orange-x1\"\u003esome orange text\u003c/p\u003e`.  \n\nYou should take a look into the other classes too, just so you know they exists (eg `full-width`, `color-primary`, `color-accent`, `bold`, ...).  \n\nI am no expert in Material theming and I'm sure there are better solutions available. Feel free to make a PR or point to some good articles/documentation.\n\n# Environments (build-time)\n## /src/environments\nBy default, there are 2 environments : Dev and prod. This is from `@angular/cli`. Remember to always **import in your app the `environment.ts`**, not `environment.prod.ts`.  \n\nIf you need to create others environments, create a file per environment and do not forget to list it in `/src/.angular-cli.json` / `apps.environments`.   \n\nBased on previous works, I've added some useful variables :\n - `production` (from `@angular/cli`). You probably won't need it. The main use of this variable is to set angular to production mode or not (avoid the double cycle of change detection to make sure data haven't change. Useful only in dev mode)  \n - `urlBackend`: Use it whenever you want to make an HTTP call to your API  \n - `mock`: Wheter you want to use some mocks or fetch the real backend. To know more about that, take a look into `/src/app/core/core.module.ts` where we use dependency injection to either have the real service or the mocked one based on this env variable  \n - `httpDelay`: When you have `mock` set to true, it might be a good idea to simulate a small latency for your http requests (300~500ms)  \n - `hashLocationStrategy`: Set it to true if you want to have your URLs in the old school mode : `my-website/#/my/spa/routing`. By default set to false and thus your URLs won't have the `#` and will look like that : `my-website/my/spa/routing`  \n - `debug`: You might use this variable to print (or not) some debug information in your app. This is different than `production` variable because you might want to display some debug in production too (eg if you create another environment `e2e-prod` where you set `production` to true, so your E2E tests run the same environment that the final one but you want the debug output in case something goes wrong)  \n\n# Environments (dynamic, at runtime)\n## /assets/runtime-environments\nSometimes, you might want to have dynamic environment variables, loaded at runtime.  \nThe main idea behind that is to be able to load it from a server, either from a given API or a simple `.json` file. That way, you can avoid to compile your project multiple times for different environments.  \n\nHow to use it: Add a `json` file per required environment in `/assets/runtime-environments`.  \nThen take a look into `/app/core/runtime-environment.service.ts`. It's a simple guard from where you can handle some logic to let the app know which `json` should be loaded. By default, it'll try to load `/src/assets/runtime-environments/runtime-environment.json`.  \n\nThen into the app, use the `RuntimeEnvironmentService` like that: `constructor(private runEnv: RuntimeEnvironmentService) {}`. And you'll be able to access your environment variable: `this.runEnv.environment`.  \n\nIf you don't want that feature and keep your main route as fast as possible without being blocked while trying to fetch the `json` file, just turn that feature off into the build environment `/src/environments/environment*.ts` (set property `loadRuntimeEnvironment` to false).  \n\n**This feature has been turned off by default**.\n\n# assets\n## /src/assets\nFolder where you can put all your static assets like pictures. There's also a `i18n` folder with one file per language. Indeed, this template includes `@ngx-translate` so you can easily have multi language support.  \n\nIf you add a language file, to make it available in the UI you'll have to open `/src/app/core/core.module.ts` and add it to the `providers` list.\n\n# Folder structure\n## AppModule\nIn every app, you need a \"main\" module (CF `/src/main.ts`) so angular can bootstrap it. With `@angular/cli` (and in general), it's called `AppModule`. You'll find it here : `/src/app/app.module.ts`.  \nI try to keep this module as simple as possible because if we need to run angular in a different environment (universal on server side or even in a web-worker), we might have to create another file (eg `app.module.universal.ts` or `app.module.webworker.ts`) which doesn't import the `BrowserModule`. Then, in those files we would simply have to import our 3 modules : `CoreModule`, `SharedModule` and `AppRoutingModule`.  \n\nKeep it simple : Don't touch it.\n\n## CoreModule\nEverything you only want to import in your app only once. (It'll mainly be modules with providers). It's here that we load our (ngrx) store, the devTools, the translate module and our (ngrx) effects.  \n\nWe'll also add our `providers` here for simplicity.  \n\nInto the `core` folder, you'll also find the `injection-tokens.ts`. It's where you can create your tokens.  \n\n## FeaturesModule\nIt's basically the folder where you'll put (nearly) all your code. With angular, your app will be splitted in (a lot of) components. I like to create a module (folder) per feature and if it's not something I'll re-use up to the tree of components, I nest it. For example, with an email application we could have :\n```\n|--src\n  |--app/\n    |--features/\n      |--login/\n      |--emails/\n        |--inbox/\n        |--newEmail/\n      |--contacts/\n```\n\n## SharedModule\nSometimes, you'll have [components|directives|interfaces|helpers|services|...] that you might want to share across the whole app. You should group them into this `SharedModule` under their common folder (components, directives, etc).\n\n## Which one of those modules should I import and where ?\n- `AppModule`: Shouldn't be imported anywhere else than `/src/main.ts`. It's done so, you don't have to worry about this one\n- `FeaturesModule`: Already imported into `/src/app/app.routing.module.ts` and it's the only place where it should be\n- `SharedModule`: **Import this module in every module you'll create deep down the tree of the `features` folder**. For example, `Material` is imported/exported into `SharedModule` and if you want to use anything from `Material`, just import it to the current module you're working on\n\nIf you have any questions about that setup, let me know by opening an issue and of course, if you see something that my be improved, feel free to make a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxime1992%2Fangular-ngrx-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxime1992%2Fangular-ngrx-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxime1992%2Fangular-ngrx-starter/lists"}