@wizsolucoes/angular-starter

Wiz Angular Starter Schematic

• Sobre
• Uso
  • Opções
    • White-label
• Sobre a aplicação gerada
  • Estrutura
  • Recursos
    • Integração NGX Wiz SSO
    • Monitoramento com Application Insights
    • Commit lint
    • Configuração Prettier
    • ReCAPTCHA
    • CI/CD
• Desenvolvimento do schematic
  • Por onde começar
  • Testando o schematic localmente
  • 1. Gerando um distribuível do schematic
    • 1a. Gere um distribuível do schematic
    • 1b. Gere uma nova aplicação e instale e execute o schematic
  • 2. Executando o schematic referenciando o código fonte
    • 2a. Faça o build do schematic
    • 2b. Execute com a CLI @angular-devkit/schematics-cli
  • Aprenda mais sobre schematics

Sobre

Schematic para gerar código boilerplate com a arquitetura de referência corporativa para aplicações Angular. Compatível somente com aplicações Angular 14.

Uso

IMPORTANTE: Este schematic supõe que a aplicação usa SASS e deve ser executado em projetos novos, pois faz a sobrescrita de arquivos.

# Gerar uma nova aplicação Angular
ng new my-app --style=scss

# Entrar na pasta da nova aplicação
cd my-app

# Adicionar arquitetura
ng add @wizsolucoes/angular-starter

# Executar testes
npm run test:ci

# Executar lint
ng lint

# Rodar aplicação
ng serve

Obs: Se você estiver usando o Git Bash e encontrar um erro ao executar ng add @wizsolucoes/angular-starter, execute o comando no Terminal do VSCode ou em PowerShell.

Obs: É necessário fazer a configuração da biblioteca NGX Wiz SSO para explorar as funcionalidades do Starter.

Opções

White-label

Ao executar o schematic, você deve escolher se a aplicação é 'White-label' ou não, respondendo este prompt na linha de comando:

? Essa aplicação é 'White-Label'? (Y/n)

Para entender mais sobre a arquitetura 'White-label', consulte a documentação neste repositório.

Sobre a aplicação gerada

Estrutura

A aplicação tem 2 partes principais:

• A parte "eager" que será carregada na inicialização na aplicação (o main.js bundle).
• A parte "lazy" composta por funcionalidades da aplicação e que será carregada sob demanda como resultado da navegação do usuário.

Esta é a estrutura de pastas proposta:

|-- core
    |-- [+] authentication
    |-- [+] guards
    |-- [+] http
    |-- [+] interceptors
    |-- [+] mocks
    |-- [+] services
    |-- [+] layout

|-- features
    |-- feature1
        |-- feature1-routing.module.ts
        |-- feature1.component.html
        |-- feature1.component.scss
        |-- feature1.component.ts
        |-- feature1.component.spec.ts
        |-- feature1.service.ts
        |-- feature1.module.ts

    |-- feature2 
        |-- [+] components
        |-- feature2-routing.module.ts
        |-- feature2.service.ts
        |-- feature2.module.ts

|-- shared
    |-- [+] components
    |-- [+] models
    |-- [+] directives
    |-- [+] pipes

|-- app-routing.module.ts
|-- app.component.html
|-- app.component.scss
|-- app.component.ts
|-- app.component.spec.ts
|-- app.module.ts

Core

O core module deve conter serviços singleton, componentes universais e outros recursos em que há uma instância única. Autenticação, header, interceptors são exemplos de componentes que terá apenas uma instância ativa para a aplicação e será utilizado praticamente por todos os modules.

Features - Módulos Lazy Loaded

Módulos lazy loaded ajudam a diminuir o tempo de inicialização da aplicação. Com o lazy load, o aplicativo não precisa carregar tudo de uma só vez. Ele só vai carregar o que o usuário espera ver. O módulo só irá carregar quando o usuário navegar para sua rota.

Observe que se o módulo de feature tiver mais de um componente, criamos sub-pastas para a cada componente (Ex. feature2) para que nenhuma pasta tenha mais de 6 arquivos conforme a recomendação do style guide do Angular.

Para gerar um novo módulo lazy loaded use a o schematic ng generate module com a flag --route. Por exemplo, para gerar uma nova rota /privacy:

ng g m features/privacy --route privacy --module app.module.ts

Shared

O shared é onde todos os componentes compartilhados, pipes, filters e services devem ir. O shared pode ser importado em qualquer module. Assim esses itens serão reutilizados. O shared module deve ser independente do restante do aplicativo. Portanto, não deve ter referências de outro módulo.

Referências

A estrutura é inspirada nas seguintes fontes:

• Como estruturar componentes em grandes projetos - Bruno Brito
• How to architect epic Angular app in less than 10 minutes! - Tomas Trajan
• Application structure and NgModules - Angular coding style guide

Recursos

O seguintes recursos já estão implementados na aplicação starter. Para alguns dos recursos é necessário fazer uma configuração antes de utilizá-los.

Integração NGX Wiz SSO

Integração com NGX Wiz SSO. Um módulo Angular feito para facilitar processo de autenticação e renovação de token no SSO da Wiz.

Configuração SSO

Adicione as configurações de SSO do seu projeto aos arquivos da pasta src/environments.

ssoConfig: {
    apiPath: '<<urldo servico>>',
    clientID: '<<Cliente ID>>',
    clientSecret: '<<Cliente Secret>>',
    grantType: '<<Grant Type>>',
    authedPaths: ['<<dns a ser autenticado>>'],
    scope: '<<scope do projeto>>',
    options: {
      // parâmetro opcional
      ssoTimeOut: 60000, // parâmetro opcional, determina o timeout para o SSO
      tokenAutoRefresh: true, // parâmetro opcional, determina se o token deve ser renovado
      loginRoute: 'login', // url que aponta para onde redirecionar no caso de não haver token
    },

O módulo do NGX Wiz SSO está importado no CoreModule.

@NgModule({
  declarations: [MainLayoutComponent, NavComponent],
  imports: [
    BrowserModule,
    RouterModule,
    HttpClientModule,
    NgxWizSSOModule.forRoot(environment.ssoConfig), // <--- import do NGX Wiz SSO
  ],
  exports: [MainLayoutComponent, NgxWizSSOModule],
})
export class CoreModule {}

O componente login tem um botão de "Entrar" que exemplifica como usar o plugin. Para entender melhor as configurações consulte a documentação do projeto NGX Wiz SSO.

Monitoramento com Application Insights

Monitoramento de erros e de performance da aplicação Angular usando o Azure Application Insights.

Configuração Application Insights

Adicione sua chave de instrumentação ao arquivo de variáveis por ambiente:

export const environment = {
  production: true,
  appInsights: {
    instrumentationKey: 'YOUR-APPLICATION-INSIGHTS-INSTRUMENTATION-KEY',
  },
};

Commit lint

As mensagens de commit devem seguir a convenção de Conventional commits que é o padrão para todos os projetos da Wiz. Este projeto já tem commit lint configurado com husky para te ajudar. Consulte a convenção Angular se tiver dúvidas sobre o tipo correto para seu commit.

Configuração Prettier

O código gerado contem arquivos de configuração da ferramenta de formatação Prettier e cria dois scripts npm:

  "scripts": {
    "//": "...",
    "format:check": "prettier **/*.{html,ts,js,json,scss} --check",
    "format:write": "prettier **/*.{html,ts,js,json,scss} --write"
  },

ReCAPTCHA

Implementação de Google ReCAPTCHA na tela de login. Adicione a chave pública do seu projeto aos arquivos da pasta src/environments.

export const environment = {
  ...
  reCaptcha: {
    siteKey: 'YOUR-RECAPTCHA-KEY',
  },
};

CI/CD

O código gerado irá conter um arquivo azure-pipelines.yml com a configuração de integração contínua de de deploy da aplicação.

Desenvolvimento do schematic

Por onde começar

# Clonar o repositório
git clone [e-mail]:wizsolucoes/angular-starter-schematic.git

# Entrar na pasta do schematic
cd angular-starter-schematic

# Instalar as dependências
npm install

# Buildar schematic
npm run build

# Executar os testes
npm test

Testando o schematic localmente

Para testar o schematic localmente, você pode gerar um distribuível do schematic, instalar como pacote em uma aplicação angular ou você pode executar o schematic referenciando o código fonte diretamente.

1. Gerando um distribuível do schematic

1a. Gere um distribuível do schematic

# Instalar as dependências
npm install

# Buildar schematic
npm run build

# Gerar tarball eg. wizsolucoes-angular-starter-1.0.1.tgz
npm pack

1b. Gere uma nova aplicação e instale e execute o schematic

# Gerar uma nova aplicação Angular em outra pasta para testar o schematic
ng new my-app --style=scss

# Entrar na pasta da nova aplicação
cd my-app

# Instalar o distribuível do schematic
npm i --no-save ../<path-to>/angular-starter-schematic/wizsolucoes-angular-starter-x.x.x.tgz

# Executar schematic
ng g @wizsolucoes/angular-starter:ng-add

2. Executando o schematic referenciando o código fonte

2a. Faça o build do schematic

# Instalar as dependências
npm install

# Buildar schematic
npm run build

2b. Execute com a CLI @angular-devkit/schematics-cli

(É preciso ter instalado a CLI com ng i -g @angular-devkit/schematics-cli)

# Gerar uma nova aplicação Angular em outra pasta para testar o schematic
ng new my-app --style=scss

# Entrar na pasta da nova aplicação
cd my-app

# Exeucutar o schematic com @angular-devkit/schematics-cli
schematics ../<path-to>/angular-starter-schematic/src/collection.json:starter

Aprenda mais sobre schematics

• Generating code using schematics
• Total Guide To Custom Angular Schematics