Criar Stack Versionada

Nesta seção, você encontra detalhes de como criar uma Stack e versioná-la.

Antes de você começar

Este tutorial cria uma Stack com Template/Plugin e versiona toda a Stack inicializando o Git com o seu repositório remoto.

Contexto

O exemplo deste tutorial cria uma Stack e um Template com um código em Javascript. A ideia é criar um Plugin que remove o arquivo em Javascript(index.js) e gera outro arquivo com um código em Typescript, o index.ts.

Depois de aplicar o Plugin, o código final terá um arquivo:

  • package.json
  • index.ts
  • tsconfig.json O Plugin transforma javascript em Typescript.

Pré-requisitos

  • O seu repositório do Git deve ser público para importar a Stack no seu ambiente.
  • Criar uma pasta com o nome “app” para realizar os testes.

Siga os passos abaixo:

Passo 1. Criar a sua Stack

Adicione o parâmetro --remote no comando para criar a Stack:

stk create stack --remote <url-repositorio>

Se você não colocar um nome para a sua Stack, o nome do seu repositório será o nome da Stack, isso acontece depois que você executar o commit para versioná-la, no próximo passo.

Stack foi criada na estrutura padrão:

│   .gitignore
│   stack.png
│   stack.yaml
│
├───docs
│       about.md
│       use-case.md
│
└───stackfiles
        default.yaml

Passo 2. Versionar a sua Stack

Execute no terminal:

git push

Se houver algum erro na sua branch, utilize o comando:

git push --set-upstream origin main

A sua Stack foi versionada!

Passo 3. Criar o Template

Execute o comando abaixo no seu terminal:

stk create template <nome-do-seu-template>

O Template foi criado na estrutura padrão:

nome-do-seu-template
│   template.yaml
│
└───templates
        README.md

Passo 4. Versionar o seu Template

Versionar a criação do seu Template na Stack. Execute os comandos:

git add .
git commit

E depois:

git push

Passo 5. Criar arquivo e editar o Template

Na pasta da Stack, clique na pasta do seu Template e dentro dela crie um arquivo com nome index.js e copie e cole o conteúdo abaixo:

helloStackSpot('{{project_name}}')

function helloStackSpot(projectName) {
  console.log(`Projeto ${projectName} criado com StackSpot!`)
  console.log('Veja mais como criar templates em: https://docs.stackspot.com/v3.7.0/docs/creators-guide/guides/howto-create-template/')
}
  • Edite o arquivo templates/template.yaml e adicione o input project_name: global: true

Confira abaixo o exemplo:

inputs:
  - label: Project name
    type: text
    name: project_name
    default: project-name
    global: true # Atributo adicionado para informar que input pode ser utilizado nos plugins aplicados

Passo 6. Versionar a alteração

Agora, execute os comandos para versionar alteração do Template na sua Stack.

git add .
git commit

E depois:

git push

Passo 7. Criar uma aplicação e testar o Template

Depois de editar o arquivo, execute o comando abaixo fora da pasta da sua Stack:

stk create app nome-do-seu-app --template-path <caminho_diretorio_template_local>

A saída no terminal deve ser:

- Application nome-do-seu-app successfully created!

Você também pode criar um app e testar o Template, execute o comando abaixo:

 stk create app nome-do-seu-app --template <nome-stack/nome-template>

O terminal retorna:

- Application nome-do-seu-app successfully created!

Pronto seu Template foi utilizado na criação de uma aplicação! Para testar acesse o diretório criado e execute o comando node index.js

O terminal retorna:

Projeto nome-do-seu-app criado com StackSpot!
Veja mais como criar templates em: https://docs.stackspot.com/v3.7.0/docs/creators-guide/guides/howto-create-template/

Passo 8. Criar o Plugin

Dentro da pasta da sua Stack, execute o comando para criar seu Plugin:

stk create plugin <typescript-plugin>

typescript-plugin é o nome do Plugin neste exemplo, você pode utilizar outro.

O Plugin tem a estrutura padrão:

typescript-plugin
    │   plugin.png
│   plugin.yaml
│
├───docs
│       about.md
│       implementation.md
│       usage.md
│       use-case.md
│
└───templates
        README.md

Passo 9. Aplicar o Plugin

Entre na pasta app, em seguida, entre na pasta da aplicação que você criou no passo 7 e execute o comando abaixo:

stk apply plugin --plugin-path <caminho-absoluto-do-plugin>

Passo 10. Versionar a alteração

Para versionar alteração do Plugin na sua Stack, execute:

git add .
git commit

E depois:

git push

Passo 11. Editar o Plugin

Acesse a pasta do Plugin que você criou, clique na pasta templates e você precisa criar 3 arquivos nessa pasta, confira abaixo:

1. Criar um arquivo com o nome index.ts e copie e cole o conteúdo abaixo:

const projectName: string = '{{project_name}}'
helloStackSpot(projectName)

function helloStackSpot(projectName: string) {
  console.log(`Projeto ${projectName} criado com StackSpot!`)
  console.log('Veja mais como criar templates em: https://docs.stackspot.com/v3.7.0/docs/creators-guide/guides/howto-create-template/')
  console.log('Veja mais como criar plugins em: https://docs.stackspot.com/v3.7.0/docs/creators-guide/guides/howto-create-plugin/')
}

2. Criar outro arquivo com nome package.json e inserir o conteúdo:

{
  "name": "{{project_name}}",
  "version": "1.0.0",
  "description": "{{project_description}}",
  "main": "index.js",
  "scripts": {
    "build": "tsc",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "MIT",
  "devDependencies": {
    "@types/jest": "^28.1.6",
    "@types/node": "^18.6.4",
    "jest": "^28.1.3",
    "ts-jest": "^28.0.7",
    "ts-node": "^10.9.1",
    "typescript": "^4.7.4"
  }
}

4. Criar outro arquivo no mesmo diretório com nome tsconfig.json e inserir o conteúdo:

{
  "compilerOptions": {
    "alwaysStrict": true,
    "charset": "utf8",
    "declaration": true,
    "experimentalDecorators": true,
    "incremental": true,
    "inlineSourceMap": true,
    "inlineSources": true,
    "lib": [
      "es2019",
      "dom"
    ],
    "module": "CommonJS",
    "newLine": "lf",
    "noEmitOnError": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "resolveJsonModule": true,
    "strict": true,
    "strictNullChecks": true,
    "strictPropertyInitialization": true,
    "stripInternal": false,
    "target": "ES2019",
    "composite": false,
    "tsBuildInfoFile": "tsconfig.tsbuildinfo"
  },
  "include": [
    "**/*.ts"
  ],
  "exclude": [
    "node_modules",
    "test/**/expected-src",
    "generated-src",
    "build/**/*"
  ],
}

Passo 12. Alterar o arquivo plugin.yaml

Na pasta da Stack, acesse a pasta do seu Plugin e abra o arquivo plugin.yaml.

Para o Plugin funcionar corretamente, você precisa fazer algumas alterações, veja abaixo:

# inputs:
#   - label: Input Example
#     type: text
#     name: example
#     default: any text
#   - label: Example of number
#     type: int
#     name: any_number
#     default: "10"
#   - label: Example of list
#     type: multiselect
#     name: any_list
#     items:
#       - item1
#       - item2

1. Remover os inputs não utilizados, mantenha apenas o input abaixo, copie o conteúdo:

inputs:
  - label: Informe a descrição do projeto
    type: text
    name: project_description
    default: Projeto Criado com StackSpot

2. Adicionar os Hook Declarativos do tipo run no arquivo plugin.yaml:

hooks:
  - type: run
    trigger: before-render
    mac:
      - rm index.js
    linux:
      - rm index.js
    windows:
      - del index.js
  - type: run
    trigger: after-render
    commands:
      - echo "Instalando dependências..."
  - type: run
    trigger: after-render
    mac:
      - npm install
      - npm run build
    linux:
      - npm install
      - npm run build
    windows:
      - npm.cmd install
      - npm.cmd run build
  - type: run
    trigger: after-render
    commands:
      - echo "Teste o plugin executando `node index`"

No final, uma mensagem é exibida e informa como fazer o teste após aplicação do Plugin.

Passo 13. Versionar a alteração

Para versionar alteração do Plugin na sua Stack, execute:

git add .
git commit

E depois:

git push

Passo 14. Testar o Plugin

Entre na pasta app, em seguida, entre na pasta da aplicação que você criou no passo 7 e execute o comando abaixo:

stk apply plugin --plugin-path <caminho-absoluto-plugin-local>

O terminal retorna:

Teste o plugin executando `node index`
- Plugin typescript-plugin applied.

Depois de versionar a Stack e fazer o push do Plugin, atualize a Stack no seu ambiente, execute:

stk update stack nome-stack

Agora, teste o Plugin com o comando abaixo:

stk apply plugin <nome-stack>/<typescript-plugin>

O terminal retorna:

Teste o plugin executando `node index`
- Plugin typescript-plugin applied.

Pronto, o seu Plugin foi utilizado em uma aplicação!

  • Para testar, execute o comando node index e o terminal retorna:
Projeto teste-template criado com StackSpot!
Veja mais como criar templates em: https://docs.stackspot.com/v3.7.0/docs/creators-guide/guides/howto-create-template/
Veja mais como criar plugins em: https://docs.stackspot.com/v3.7.0/docs/creators-guide/guides/howto-create-plugin/