Git Product home page Git Product logo

generator-ngx-rocket's Introduction

πŸš€ generator-ngx-rocket

NPM version Build Status Node version XO code style Downloads

ngx-rocket logo

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

See generated project example here.

Benefits versus bare angular-cli projects

  • 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, Cordova integration

  • Extensive base documentation: coding guides for TypeScript/SCSS/HTML, Angular onboarding guide, corporate proxy and other tools configuration and usage...

  • Ready-to-use UI components: focus on your app, not on the stack! Choose between a Bootstrap 5, Ionic or Angular Material based UI with nicely looking, responsive starter templates

  • Mobile/desktop hybrid app support: choose between a web app, a mobile app (using Cordova), a desktop app (using Electron) 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! See What's in the box for more details.

Getting started

  1. Install required tools:
npm install -g generator-ngx-rocket
  1. Create your application:
ngx new

πŸ’‘ Pro tip: the ngx CLI can do more that just bootstrapping new projects! You can use it to run your NPM scripts with fuzzy matching (try ngx ci for example) or help you maintaining your project up-to-date. Take a look at the full documentation!

Project structure

The structure follows Angular 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 on NPM scripts.

Task Description
npm start Run development server on http://localhost:4200/
npm run serve:sw Run test server on http://localhost:4200/ with service worker enabled
npm run build [-- --configuration=production] Lint code and build web app for production (with AOT) in dist/
npm test Run unit tests via Karma or Jest in watch mode
npm run test:ci Lint code and run unit tests once for continuous integration
npm run e2e Run e2e tests using Cypress
npm run lint Lint code
npm run translations:extract Extract strings from code and templates to src/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 in dist/ folder
npm run cordova:clean Removes www/, platforms/ and plugins/ 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 is production.

Development server

Run npm start 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 proxy configuration by default.

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.

What's in the box

starter kit

The app template is based on HTML5, TypeScript and Sass. The translation files use the common JSON format.

Tools

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

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

Native mobile application bundling is based on Cordova. Ionic WKWebView is used for iOS for better performance.

Libraries

Coding guides

Other documentation

Generator options

  • --packageManager [npm|yarn]: specify whether to use Yarn or NPM as your package manager (default is NPM). You can also use the environment variable NGX_PACKAGE_MANAGER to set this option globally.
  • --automate <json_file>: automate prompt answers using specified JSON file (see here for examples).
  • --addons <addon_name> [<addon_name>] ...: space-separated list of add-ons to use.
  • --no-update: do no update existing project (see also updating generated projects).
  • --no-analytics: do not report anonymous usage analytics. You can also use the environment variable NGX_DISABLE_ANALYTICS to 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 strategy to use in Angular router (default is path).
  • --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 to core/shared folders.
  • --deploy <option>: choose automatic deployment option. Use ngx n --deploy to see possible values.

When generating a fullstack project (with both client and server code), you can use the environment variables NGX_CLIENT_PATH and NGX_SERVER_PATH to 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. Run ngx update using the CLI inside 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 --tools option 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 the addon sub-generator of the CLI:

ngx new --addon

See the add-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 the contributing guide. If you want to help and don't know what you can do, look for good first contribution issues, or if you're a seasoned OSS contributor look for PR welcome tags.

Thanks for helping ❀️

License

MIT

generator-ngx-rocket's People

Contributors

angular-cli avatar athisun avatar bursauxa avatar captaincaius avatar creal73 avatar dependabot[bot] avatar dmnktoe avatar dvaji avatar ekhozie avatar fabiomartino avatar flomaetschke avatar gaetanmaisse avatar isaax2 avatar justerror avatar luisreinoso avatar luiza-cicone avatar marlonluan avatar pascalif avatar patelvimal avatar pathway27 avatar ramohio avatar reflexdemon avatar semantic-release-bot avatar sinedied avatar skorunka avatar snowyu avatar veneliniliev avatar vincentbostoen avatar wnabil avatar yashanand1910 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

generator-ngx-rocket's Issues

Contributing

Hi,
I wanted to look a bit at the generator... and maybe help... But I can't find how to start with it.
How is your environment?
How do you test the generator itself?

In the README.md of this repo, we can learn how to use the generator. But not how to develop/contribut.
Could you write somehting about it please?

Thank you

Assets hosting

Dummy issue to host assets for GH presentation πŸ˜„

What about AOT?

Hi,
as far as I can see AOT support is not included by default? Any chance to see it in next release?

Create an Http service extension

Provide support for server configuration depending of the environment, default headers and user-configurable cache policy.

Should go in core module.

Hightlight the value proposition of the starter-kit

I think the current documentation currently lacks explaining the value proposition of the starter-kit compared to going straight with the anguar-cli. In the README, we currently have:

Web project starter kit including 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

I think it would be a nice addition to clearly explain the advantages of bootstraping a new projet from the starter-kit instead of the angular-cli. Back to the Angular 1.x world, because there was no cli so everyone was looking for a starter-kit to speed up their development. Now that the angular-cli is out, I think we should explain why using a starter-kit still makes a lot of sense.

Ideas?

Improve folder structure for large app

Looking into the app structure, I'm wondering how the app will scale on large apps. Mostly around the organization and creation of new components.
As I like to see apps in general, some components are state-full (home page, about page for example) and some other are state-less (a nav bar component).
Looking at the way the app is made, all pages components are at the /app root folder, where the header component is in the /app/shared folder.
would that make more sense if we could have a better separation between components? like:

|- app/                      app components
|  |- container/          container components
|  |  |- home/
|  |  |- home/
|  |- shared/                shared module  (common components, directives and pipes)
|  |  |- header/
|  |  |- nav/
|  |- app.component.*        app root component (shell)
|  |- app.module.ts          app root module definition
|  |- app-routing.module.ts  app routes

In that case, let say I want to add some redux state manager in my app, I will be able to add a redux folder aside with container and shared (maybe core as well, not sure I get why it's separated from the shared folder..). This way, I get a clear view of area of code I'm dealing with without having to find my /shared or /redux folder with the rest of the app...

It's definitively more an open discussion than anything else but I wanted to get a bit of your input and understand if you had some issue when scaling the app regarding to the app structure.

Port mobile template to NG2

In a separate branch, port SK mobile template to Angular 2, using Ionic v2 instead of Bootstrap v4/Font Awesome.

Warning: the build system should still be using angular-cli, not the ionic-cli. The project template/structure should be compatible with the web template (as it should be interchangeable later).

Here are the list of tasks I have in mind, feel free to suggest changes:

  • Create the feature branch with generator questions
  • Add the Ionic/mobile specific app configuration (onReady...) and base templates (no auth)
  • Add authentication templates and make authentication/guard working with Ionic
  • Detect device locale/language on startup and setup i18n accordingly using cordova-plugin-globalization
  • Create npm scripts for: cordova passthrough (like for angular-cli), prepare, build, run... with Android + iOS support
  • Improve the templates with common/recommended plugins: cordova-plugin-splashscreen, cordova-plugin-device, cordova-plugin-whitelist etc
  • Add service worker/PWA support => will be in a separate update/issue
  • Add generator questions (or use by default?) + configuration for Crosswalk (legacy devices) and WKWebView
  • Add platform choice (Android, iOS, ...) with generator questions
  • Add cordova usage guide

Warning on build

There is currently this warning on build, due to a change in the angular-cli webpack config:

WARNING in ./~/encoding/lib/iconv-loader.js
9:12-34 Critical dependency: the request of a dependency is an expression

This is due to the @biesbjerg/ng2-translate-po-loader package, and we have no means of correction as for now.

The only way would be to move from .po translations files to plan .json files, and would probably be related to #3

Add yarn option instead of npm

yarn is an alternative to NPM, with (almost) only benefits:

  • faster, with better caching support
  • more dev-friendly (use yarn test:ci instead of npm run test:ci with no silly noise
  • lock dependencies by default (like shrinkwrap)

It would be nice to add a generator option to use yarn instead of npm, while keeping npm as the default as it needs to extra package to install.

Tasks:

  • Update @ngx-rocket/core to add --packageManager option
  • Update @ngx-rocket/core core docs
  • Support overriding default package manager throughNGX_PACKAGE_MANAGER env variable
  • Update generator-ngx-rocket to use specified package manager
    • update package.json scripts and other templates if applicable
    • update console output
  • Adapt updating, proxy and cordova guides in consequence
  • Add a yarn test case to CI
  • Update addons to use specified package manager
  • Update @ngx-rocket/scripts to use specified package manager, either through the .yo-rc file or NGX_PACKAGE_MANAGER env var
  • Update CLI to use specified package manager, either through the .yo-rc file or NGX_PACKAGE_MANAGER env var
  • Update generator-ngx-rocket-addon
  • Add warning for cordova projects
  • Add documentation on generator option

Add authentication screens/workflow

Since most of the apps we'll create will use an authentication method method with eventually a login/logout screen, it could be interesting to provide the ground for this in this SK.

I imagine it would take the form of an additional auth component, with a dedicated overridable service with a mock implementation to start with, ability to save credentials for returning users and an auth guard redirecting to the login screen if the user is not authenticated.

Seems pretty "standard" to me, but do not hesitate to complete or discuss this approach if needed.

Improve typescript rules

Should we force typing in all/some cases?

What could be improved over default rules? What would benefit from being enforced?

The <template> element is deprecated

Seems like ngx-app is using the old <template> tag which was deprecated recently in favour of ng-template

Reproducing:

  • npm install -g yo generator-ngx-app && yo ngx-app
  • open the localhost:4200
  • open console
  • refresh to get a new set of warnings (it shows after the [App] init from the logger.service.ts

Proposal: add IDE-specific configuration

This should come after the yeoman generator is done, but we could provide opt-in IDE/code editors configuration, like:

  • Jetbrains' IDE (webstorm, intellij...)
  • Visual Studio Code
  • any ideas?

As far a the target IDE supports it, we could add code-style/formatting settings as well as tool/run configuration pre-bound to the npm tasks.

What do you think?

Add doc to explain HTML5 routing

In light of #23, Add doc to explain HTML5 routing and explain potential server issues with some hints on how to resolve it (url rewriting).
If possible, also provide typical common server configs (express...)

Is it just me or is URLSearchParams() being ignored by the HttpService?

So: This is a raw angular2.4 plunkr I found laying about: https://plnkr.co/edit/TTsy3IsY8t0hmo8Z0LaA?p=preview

The same cannot be done using this application (I failed to create a plunkr with the generator-ngx-app);

let search: URLSearchParams = new URLSearchParams();

Object.keys(data).forEach((key: string) => {
    search.set(key, data[key]);
});
console.log(search)
let options: RequestOptions = new RequestOptions({search});

this.http.get(<string>_endpoint, options)

This will make the HTTP call but ignore all the URLSearchParams that are inside options

Integrate stylelint plugin for browsers features linting

As of stylelint/stylelint#2123, the no-unsupported-browser-features rule of stylelint is deprecated and will be removed in the upcoming 8.x version. This triggers a deprecation warning during the lint command as for now.

As per their recommendation, if no one took the job in the meantime, we should extract the current code for this rule into a separate stylelint plugin to fill the hole and remove the warning.

Create github page for the project

As the issue on the website was lost, I'll recap here the remaining task for the website:

Tasks:

  • Add open graph meta tags
  • Add addons page to list available addons on NPMs, filtered by a static json blacklist
  • Add form (google forms?) to submit person/companies using the project
  • Add blog tab that redirects to ngx rocket
  • Use hashbang routing instead of HTML5 mode to fix F5 issues (to be replaced later by a proper NodeJS server acting as a reverse proxy?)

Old issue description:

  • Setup a Jekyll template for github pages deployment
  • Write some promotion/communication stuff about the goals and benefits

For the design, use these for inspiration: http://fountainjs.io, https://github.com/CloudCannon/cause-jekyll-template, https://github.com/CloudCannon/hydra-jekyll-template

The idea would be to have a nice 1-page website with scroll hooks and links to github/npm etc.

Improve i18n workflow

Use the "official" tools as explained here: https://angular.io/docs/ts/latest/cookbook/i18n.html

  • Update templates to be i18n ready
  • Provide example for 2 languages (en/fr)
  • Setup task to extract/import translations files

Note that it was planned at some point that .po format should be supported, which does not seems to be the case at the moment.

Port SK web template to angular-2

Use angular-cli as a start for the tooling,
Then port the web template using:

  • Angular 2 (obviously)
  • Bootstrap 4
  • Font Awesome
  • Same responsive design (or close enough)

Create a customizable cache service

Provides support for various cache policies (in-memory, local storage...) for the Http service.

Use hints from SK1 and adapt it to angular 2.

New home and renaming the project

Because we have awesome upcoming features for this project (like #33) and to allow us to associate the forthcoming family of tools (cli, addon generators, etc...) with a unique, distinct name we created a new home: πŸš€ ngX-Rocket

As part of this effort, we also renamed the generator name and NPM package to generator-ngx-rocket. Why? The ngx prefix alone, along with the starter kit were too generic to distinguish ourself and what we are doing from the crowded space of Angular project starters, so we went for a new naming to give our effort a distinct identity.

We aim to be more open than ever, build a community around the project and hope to gather development effort around customized starter kits in reusable addons generators instead.

Allow update of existing projects

To simplify update process for existing generated project, if a previous config is found it should be used to replay automatically the generator and allow updating from a newer generator version.

A warning should also be issued to warn the user of uncommited changes, to prevent issues.

Support the starter-kit via the dotnet new command ?

With the release of VS2017 comes a new update for .Net Core. This update will bring a better experience for the dotnet new command to scaffold new projects, including support for custom templates.

image

Do you think that would be useful to have a template for the starter-kit?

  • This post explains the new experience with dotnet new
  • This post explains how to create a custom template
  • The code for the template engine used by dotnet new is available here.

Init project seed with angular-cli

The base project seed should include:

  • Tooling (angular-cli at the moment)
  • Quickstart doc (env install and dev start)
  • Tasks to run serve / build / unit tests / e2e tests (npm tasks or plain angular-cli commands)
  • Multiple env management (dev / prod at least in the seed)

erreur sur la commande npm install

j'a l'erreur suivante quand je lance la commande npm install :

ERROR in ./src/app/core/i18n.service.ts Module build failed: Error: C:/Users/Thales/Documents/GitHub/ngx-starter-kit/src /app/core/i18n.service.ts (3,10): Module '"C:/Users/Thales/Documents/GitHub/ngx- starter-kit/node_modules/@types/lodash/index"' has no exported member 'includes' .) at _checkDiagnostics (C:\Users\Thales\Documents\GitHub\ngx-starter-kit\node_ modules\@ngtools\webpack\src\loader.js:145:15) at C:\Users\Thales\Documents\GitHub\ngx-starter-kit\node_modules\@ngtools\we bpack\src\loader.js:172:17 @ ./src/app/app.component.ts 22:0-50 @ ./src/app/app.module.ts @ ./src/main.ts @ multi webpack-dev-server/client?http://localhost:4200/ ./src/main.ts

j'ai l'impression que la dernière version de lodash fout le bordel. Quand je force la version en virant le "^" sur @types/lodash dans le package.json (ligne 43) ça marche.

Window service wrapper

Should we add a window service wrapper into Angular DI system (to allow mocking in unit tests)?

I tried a quick implementation using a custom provider with injecting directly the window value into the core module, but it did not work, need to investigate...

CLI and composition with other possible addons generators

Once #6 is done, a welcome suggestion (thanks @R0muald) was to provide a way to compose the base SK generator with any other "addon" generators.

One way could be to investigate yeoman's composability features or maybe create a custom CLI to simply wraps the generators setup/install/running.

The basic idea is to gather in a simple way for the user the ability to mix the SK with addon generator, something like:

$ ngx new myAwesomeProject --addons="myCompanyUiLibrary someBackendGenerator"

or even maybe

 # performs `npm install` + register addons with ngx cli
$ ngx addon install myCompanyUiLibrary someBackendGenerator
# registered addons will be used by default
$ ngx new myAwesomeProject

Yeoman also support generating a project from multiple generators, so we should also consider this.

Remaining tasks

  • Extract generator code in a separate package
  • Add template prefix to allow merging json files
  • Refactor base generator to use core
  • Create an example addon generator
  • Create CLI
  • Create generator for making addons
  • Add documentation
  • Create new issues for blueprints support...

Base libraries

Hi,
I'm carefully watching this repo because good practices are there & sharded ;)

I would like to give my thought about the embedded libraries... (hope I can :p)
I feel that a pro starter kit should have:

  • as less dependency as possible
  • guides to help users on how to use the kit and how to make it working it with libs

For example, you are using Font Awesome just to add few icons in menu / header... maybe we should be able to set these icons from outside of these components. And provide a guide on how to embed Font Awesome.

You are also selecting Bootstrap, I feel that it's a too "strong" choice :). So it can be an example... but not part of the starter kit.

I would like to see more something like: angular/flex-layout

//let's speak// :)

New logo for ngx-rocket

After the project renaming, we are looking for a new and nice logo to illustrate the ngX-Rocket ecosystem!

Here is a (bad) draft I thought up quickly:
ngx-rocket-logo-poc

A cleaner version:
ngx-rocket-clean

Another shot based on some of @gaetanmaisse ideas:
ngx-rocket-alt

More refined, thinner font:
ngx-rocket-alt-thin

A few more tries, adding a ionic-like electron and with material blue or angular red + black like @gaetanmaisse:
ngx-rocket-material-bi
ngx-rocket-material-bi-red

I you have better ideas and design skills, feel free to propose 🎨 !

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.