🚀 generator-ngx-rocket

Extensible Angular 14+ enterprise-grade project generator based on angular-cliwith best practices from the community. Includes PWA, Cordova & Electron support, coding guides and more!

See generated project examplehere.

Benefits versus bareangular-cliprojects

• A complete starter template:example app structure tailored for scalability, with examples and boilerplate code for every common thing needed in enterprise projects, such as unit tests, routing, authentication, HTTPS service extensions, i18n support with dynamic language change and automatic user language detection...

• Improved tooling:SCSS & HTML linting, stricter TSLint rules, markdown-based local wiki server for documentation, automated localizable strings extraction, corporate proxy support,Cordovaintegration

• Extensive base documentation:coding guidesfor TypeScript/SCSS/HTML, Angular onboarding guide, corporate proxy and other toolsconfiguration and usage...

• Ready-to-use UI components:focus on your app, not on the stack!Choosebetween a Bootstrap 5,Ionicor Angular Materialbased UI with nicely looking, responsive starter templates

• Mobile/desktop hybrid app support:choose between a web app, a mobile app (usingCordova), a desktop app (usingElectron) or all at the same time using the same code base

• API proxy example setup:develop and debug faster using any remote server

• Generator output customization:with the provided add-on support,start multiple projects even faster by plugging in additions that fit your needs, such as your enterprise theme, SSO authentication, services integrations...

And there's even more! SeeWhat's in the boxfor more details.

Getting started

UsingngX-Rocket CLI

1. Install required tools:

npm install -g generator-ngx-rocket

2. Create your application:

ngx new

💡 Pro tip: thengxCLI can do more that just bootstrapping new projects! You can use it to run your NPM scripts with fuzzy matching (tryngx cifor example) or help you maintaining your project up-to-date. Take a look at thefull documentation!

Project structure

The structure followsAngular style guide.

dist/ app production build
docs/ project docs and coding guides
cypress/ end-to-end tests
src/ project source code
|- app/ app components
| |- @shared/ shared module (common components, directives, pipes and services)
| |- app.component.* app root component (shell)
| |- app.module.ts app root module definition
| |- app-routing.module.ts app routes
| +-... additional modules and components
|- assets/ app assets (images, fonts, sounds...)
|- environments/ values for various build environments
|- theme/ app global scss variables and theme
|- translations/ translations files
|- 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
reports/ test and coverage reports
proxy.conf.js backend proxy configuration

Main tasks

Task automation is based onNPM scripts.

Task	Description
npm start	Run development server onhttp://localhost:4200/
npm run serve:sw	Run test server onhttp://localhost:4200/with service worker enabled
npm run build [-- --configuration=production]	Lint code and build web app for production (withAOT) indist/
npm test	Run unit tests viaKarmaorJestin watch mode
npm run test:ci	Lint code and run unit tests once for continuous integration
npm run e2e	Run e2e tests usingCypress
npm run lint	Lint code
npm run translations:extract	Extract strings from code and templates tosrc/app/translations/template.json
npm run docs	Display project documentation

Additional tasks for Cordova-based projects:

Task	Description
npm run cordova:prepare	Prepare for building mobile app (restore Cordova platforms and plugins)
npm run cordova:run <ios/android> [--device]	Run app on target platform device or simulator
npm run cordova:build [-- --configuration=production]	Build mobile app for production indist/folder
npm run cordova:clean	Removeswww/,platforms/andplugins/folders

Additional tasks for Electron-based projects:

Task	Description
npm run electron:build	Build desktop app
npm run electron:run	Run app on electron
npm run electron:package	Package app for all supported platforms

When building the application, you can specify the target configuration using the additional flag --configuration <name>(do not forget to prepend--to pass arguments to npm scripts).

The default build configuration isproduction.

Development server

Runnpm startfor a dev server. Navigate tohttp://localhost:4200/.The app will automatically reload if you change any of the source files. You should not useng servedirectly, as it does not use the backend proxy configuration by default.

Code scaffolding

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

If you have installedangular-cliglobally withnpm install -g @angular/cli, you can also use the commandng generatedirectly.

What's in the box

The app template is based onHTML5,TypeScriptand Sass.The translation files use the commonJSONformat.

Tools

Development, build and quality processes are based onangular-cliand NPM scripts,which includes:

• Optimized build and bundling process withWebpack
• Development serverwith backend proxy and live reload
• Cross-browser CSS withautoprefixerand browserslist
• Asset revisioning forbetter cache management
• Unit tests usingJasmine,Karmaand headless Chrome
• End-to-end tests usingCypressorProtractor
• Static code analysis:TSLint,Codelyzer, StylelintandHTMLHint
• Local knowledgebase server usingHads
• Automatic code formatting withPrettier
• Deployment with the CLI usingng deploy

Progressive Web App (PWA)support provided by @angular/service-worker.

Native mobile application bundling is based onCordova. Ionic WKWebViewis used for iOS for better performance.

Libraries

• Angular
• RxJS
• ngx-translate
• UI based on:
  • Bootstrap
    • Bootstrap 4
    • ng-bootstrap
    • Font Awesome
  • Ionic:
    • Ionic
    • Ionic Native
  • Angular Material
    • Angular Material
    • Angular Flex Layout
    • Material Icons
• Optional utility libraries:
  • Lodash
  • Ramda
  • Moment.js
  • Date-fns
  • Jest

Coding guides

• Angular
• Ionic
• TypeScript
• Sass
• HTML
• Unit tests
• End-to-end tests

Other documentation

• I18n guide
• Working behind a corporate proxy
• Updating dependencies and tools
• Using a backend proxy for development
• Browser routing
• Cordova
• Electron

Generator options

• --packageManager [npm|yarn]:specify whether to useYarnor NPM as your package manager (default is NPM). You can also use the environment variableNGX_PACKAGE_MANAGERto set this option globally.
• --automate <json_file>:automate prompt answers using specified JSON file (see herefor examples).
• --addons <addon_name> [<addon_name>]...:space-separated list of add-ons to use.
• --no-update:do no update existing project (see alsoupdating generated projects).
• --no-analytics:do not report anonymous usage analytics. You can also use the environment variableNGX_DISABLE_ANALYTICSto set this option globally.
• --raw:do not use any UI library for templates.
• --tools:generate only the toolchain, without application template.
• --location-strategy [hash|path]:location strategyto use in Angular router (default ispath).
• --no-git:do not initialize git repository.
• --no-strict:disable TypeScript strict type checking options.
• --skip-quickstart:disable quick start message after project generation.
• --no-prefix:do not add@prefix tocore/sharedfolders.
• --deploy <option>:choose automatic deployment option. Usengx n --deployto see possible values.

When generating afullstackproject (with both client and server code), you can use the environment variables NGX_CLIENT_PATHandNGX_SERVER_PATHto customize the paths for client and server code. Be aware though that some add-ons may force specific paths that will preempt your changes.

Updating generated projects

As new features and newer libraries and tools are added to the generator, you may want to update your project at some point. Here is how we suggest you to do it:

1. Make sure your working directory is clean (no pending / uncommited changes).
2. Runngx updateusing theCLIinside your project folder.
3. The generator will then run again using the same options you used initially, prompting you for each file change. From there the recommended approach is simply to overwrite everything.
4. Finally, use your source control to see the diff for each file and merge the changes manually.

Note: you can use the--toolsoption to generate only the toolchain and not application templates, thus reducing the number of changes to merge.

Customize project generation

You can customize the generator output to change or enhance it to better suit your needs using add-ons.

To create a new add-on, you can use theaddonsub-generator of theCLI:

ngx new --addon

See theadd-on generator documentation for more information about add-on creation.

Contributing

First time contributors are welcome in this project! 🎉

To get started, take a look at thecontributing guide. If you want to help and don't know what you can do, look forgood first contribution issues,or if you're a seasoned OSS contributor look forPR welcome tags.

Thanks for helping ❤️

License

MIT