Quickstart

Nesta seção, você encontra detalhes de como criar e testar localmente uma Stack com Plugins, Templates e Stackfiles.

Antes de você começar

Uma Stack é um conjunto de Plugins, Templates, e Stackfiles que, quando usados em conjunto, tornam possível criar uma aplicação, projeto ou funcionalidade.

Para criar a sua Stack verifique:

  • STK CLI está atualizado
  • Git está atualizado
  • Opcional: Crie um repositório dedicado para publicar a sua Stack. Você pode criá-lo em qualquer plataforma de hospedagem de código Git (como GitHub ou GitLab) e pode ser público ou privado.

Passo 1. Estruturar o seu projeto

O código que você irá criar ou utilizar para criar uma Stack deve ser pensado em uma separação de funções, o que deve definir o conteúdo do Template e do Plugin na sua Stack. O Template deve conter o código base ou scaffold do projeto, enquanto o Plugin deve conter o código que vai adicionar novas capacidades ao código base do Template. Além disso, independente da linguagem utilizada os dois arquivos precisam ter a mesma estrutura.

Confira abaixo o exemplo de uma página HTML com um script. É desse código que será abstraído o conteúdo do Template e do Plugin. Clique nos títulos para ver o conteúdo:

1. Projeto de página HTML
<!DOCTYPE html>
<html lang="en">
<head>
    <title>My App: {{inputs.project_name}}</title>
    <meta charset="utf-8" />
    <meta http-equiv="x-ua-compatible" content="ie=edge, chrome=1" />
    <script>
        document.addEventListener("DOMContentLoaded", function() {
            var name = prompt("What is you name stacker?")
            document.body.innerHTML = document.body.innerHTML.replace('Stacker', name);
        });
    </script>
</head>
<body>
<div class="wrapper">
    <a href="https://www.stackspot.com" class="logo" target="_blank" rel="noopener noreferrer">
        <img src="logo.png" alt="StackSpot" />
    </a>
    <div class="illustration">
        <img src="img.png" alt="illustration" />
    </div>
    <div>
        <h1 class="title">{{ inputs.greeting_message }} Stacker!</h1>
        <p class="description">
            <br>Parabéns por chegar até aqui! </br>
            <br>Agora que você já conhece nosso produto, que tal criar algo de verdade!
            </br>
            <br>Utilizando nossos estúdios você conseguirá criar uma API em minutos, bora tentar?</br></p>
    </div>
    <a href="https://www.stackspot.com/studios" class="button" target="_blank" rel="noopener noreferrer">Visitar Estúdios </a>
</div>
</body>
</html>
2. Código para o Template

O Template é Obrigatório para uma Stack, no exemplo abaixo o script que possui uma ação foi removido do conteúdo do HTML, dessa forma, restou apenas o código base para o Template de uma página HTML:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>My App: {{inputs.project_name}}</title>
    <meta charset="utf-8" />
    <meta http-equiv="x-ua-compatible" content="ie=edge, chrome=1" />
</head>
<body>
<div class="wrapper">
    <a href="https://www.stackspot.com" class="logo" target="_blank" rel="noopener noreferrer">
        <img src="logo.png" alt="StackSpot" />
    </a>
    <div class="illustration">
        <img src="img.png" alt="illustration" />
    </div>
    <div>
        <h1 class="title">{{ inputs.greeting_message }} Stacker!</h1>
        <p class="description">
            <br>Parabéns por chegar até aqui! </br>
            <br>Agora que você já conhece nosso produto, que tal criar algo de verdade!
            </br>
            <br>Utilizando nossos estúdios você conseguirá criar uma API em minutos, bora tentar?</br></p>
    </div>
    <a href="https://www.stackspot.com/studios" class="button" target="_blank" rel="noopener noreferrer">Visitar Estúdios </a>
</div>
</body>
</html>
3. Código para o Plugin

O Plugin é Opcional para uma Stack, no exemplo abaixo, o script que possui uma ação foi recortado do HTML, estabelecendo o código base para o Plugin de uma página HTML:

<!DOCTYPE html>
<html lang="en">
<head>
    <script>
        document.addEventListener("DOMContentLoaded", function() {
            var name = prompt("What is you name stacker?")
            document.body.innerHTML = document.body.innerHTML.replace('Stacker', name);
        });
    </script>
</head>
</html>

Passo 2. Criar uma Stack vazia

A Stack é constituida pelo conjunto estruturado de Templates e Plugins com a finalidade de acelerar criação de aplicações ou ambientes. Para criar a estrutura que vai unir os seus Templates e Plugins, siga os passos abaixo:

Execute o comando abaixo para criar uma Stack:

stk create stack <nome-da-stack-que-será-criada>

Por exemplo:

stk create stack hello-stacker

Opcional: Associe a URL de um repositório na criação da Stack. Para isso, no lugar do nome, execute o comando com o argumento -R ou --remote. Confira o exemplo: stk create stack --remote <url-repositório-git>

Agora, coloque uma descrição para a sua Stack, preencha o campo Description:

➜  ~ stk create stack hello-stacker
? Description:  (Describe your stack explaining its purpose) Stack para construir páginas HTML.

Passo 3. Conferir se a Stack foi criada

Nesse exemplo, a Stack foi criada depois que um repositório Git foi inicializado. Nesse repositório está o arquivo stack.yaml que descreve os dados da Stack, como descrição, nome etc.
Confira se uma pasta com o nome que você escolheu para a sua Stack foi criada. Pelo terminal, acesse a pasta:

cd <nome-da-stack-criada>

Exemplo:

cd hello-stacker

Passo 4. Criar e Testar um Template

O Template contém a base ou scaffold de um projeto, para criar e testar o Template com o seu código, siga os passos abaixo:

Entre na pasta da Stack e execute o comando abaixo (sem chaves “< > “):

stk create template <TEXTO-COM-O-NOME-DO-TEMPLATE>

Exemplo:

stk create template hello-stacker-template

Na criação do Template, você pode informar alguns argumentos para o comando. Os argumentos devem ser inseridos antes do nome do Template no campo opções stk create template <opções> <nome-do-template>. Você pode consultar as opções pelo terminal, execute o comando com o argumento de ajuda:

stk create template --help
Ou clicar aqui para ver as opções de argumentos disponíveis:
OpçãoArgumentoDescrição
Descrição-d ou --description “Texto”O texto que descreve o Template e seu propósito.
Remote-R ou --remote <git-remote-url>Configura uma URL do Git como origem do repositório do Template. É obrigatório quando o nome do Template não é preenchido, quando preenchido, o nome do Template será o nome do repositório Git.

O tipo do Template sempre será app-template, que neste caso vai gerar uma aplicação, que será a página HTML. Em seguida preencha o campo Template description:

➜  hello-stacker git:(main) stk create template hello-stacker-template
? Template types: [app-template]
? Template description:  (Describe your template explaining its purpose) Template base para uma página HTML.

Adicionar o seu código no Template

Após criar o Template em sua Stack, a Stack terá a seguinte estrutura:

➜  hello-stacker git:(main) ✗ tree
.
├── docs
│   ├── about.md
│   └── use-case.md
├── hello-stacker-template
│   ├── template.yaml
│   └── templates
│       └── README.md
├── stack.png
├── stack.yaml
└── stackfiles
    └── default.yaml  

Adicione o código no Template:

1. Acessar a pasta templates:

Dentro da pasta da Stack, acesse a pasta templates dentro da pasta do seu Template.

Sem chaves “< > “, execute no terminal:

cd <TEXTO-COM-O-NOME-DO-TEMPLATE>/templates/

Exemplo:

cd hello-stacker-template/templates/

2. Adicione o arquivo com o código do Template

Abra um editor de código, por exemplo o VSCode, e crie ou adicione o arquivo com o código do Template.

Para o exemplo com o Template da página HTML:

  1. Crie o arquivo index.html;
  2. Adicione o Código para o Template;
  3. Ao final, salve o arquivo.

Ao final a pasta templates deve conter o arquivo com o código do Template.

➜  templates git:(main) ✗ tree
.
├── README.md
└── index.html

0 directories, 2 files

Testar o Template

1. Criar uma aplicação de teste

Escolha qualquer pasta para criar a aplicação, abra o terminal e então execute (sem chaves “< > “) o comando abaixo:

stk create app <TEXTO-COM-O-NOME-DO-APP> -p <TEXTO-COM-O-CAMINHO-DA-PASTA-DO-TEMPLATE>

Exemplo:

stk create app Test1 -p /Users/StackSpot.User/hello-stacker/hello-stacker-template

Acesse a pasta escolhida no começo desse passo e confira se uma pasta com o nome dado para a aplicação e o arquivo adicionado no Template foram gerados. Para o exemplo do Template do HTML você terá em sua aplicação algo como:

➜  Test1 git:(main) tree
.
├── README.md
├── index.html
└── stk.yaml

0 directories, 3 files

Passo 5: Criar e testar um Plugin

O Plugin é uma peça de código que adiciona alguma capacidade ao seu código base ou scaffold. Para criar e testar o seu Plugin, siga os passos abaixo:

Entre na pasta da Stack e execute o comando abaixo (sem chaves “< > “):

stk create plugin <TEXTO-COM-O-NOME-DO-PLUGIN>

Exemplo:

stk create plugin hello-stacker-plugin

Na criação do Plugin, você pode informar alguns argumentos para o comando. Os argumentos devem ser inseridos antes do nome do Plugin no campo opções stk create plugin <opções> <nome-do-plugin>. Você pode consultar as opções pelo terminal executando o comando abaixo com o argumento de ajuda:

stk create plugin --help
Ou clicar aqui para ver as opções de argumentos disponíveis:
OpçãoArgumentoDescrição
Descrição-d ou --description “Texto”O texto que descreve o Plugin e seu propósito.
Remote-R ou --remote <git-remote-url>Configura uma URL do Git como origem do repositório do Template. É obrigatório quando o nome do Template não é preenchido, quando preenchido, o nome do Template será o nome do repositório Git.

O tipo do Plugin será sempre app, neste caso o Plugin vai adicionar capacidades em uma aplicação, que será a página HTML. Em seguida preencha o campo Plugin description:

➜  hello-stacker git:(main) ✗ stk create plugin hello-stacker-plugin
? Plugin types: [app]
? Plugin description:  (Describe your plugin explaining its purpose) Plugin que adiciona em uma página HTML um script para perguntar o nome de quem acessa a página.

Adicionar o seu código no Plugin

Após criar o Plugin em sua Stack, a Stack terá a seguinte estrutura:

➜  hello-stacker git:(main) ✗ tree
.
├── docs
│   ├── about.md
│   └── use-case.md
├── hello-stacker-plugin
│   ├── docs
│   │   ├── about.md
│   │   ├── implementation.md
│   │   ├── usage.md
│   │   └── use-case.md
│   ├── plugin.png
│   ├── plugin.yaml
│   └── templates
│       └── README.md
├── hello-stacker-template
│   ├── template.yaml
│   └── templates
│       ├── README.md
│       └── index.html
├── stack.png
├── stack.yaml
└── stackfiles
    └── default.yaml

7 directories, 15 files 

Adicione o código no Plugin:

1. Acessar a pasta templates:

Dentro da pasta da Stack, acesse a pasta templates dentro da pasta do seu Plugin.

Sem chaves “< > “, execute no terminal:

cd <TEXTO-COM-O-NOME-DO-PLUGIN>/templates/

Exemplo:

cd hello-stacker-plugin/templates/

2. Adicione o arquivo com o código do Plugin

Abra um editor de código, por exemplo o VSCode, e crie ou adicione o arquivo com o código do Plugin. Para o exemplo com o Plugin para a página HTML, crie o arquivo index.html e adicione o Código para o Plugin. Ao final, salve o arquivo.

Ao final a pasta templates deve conter o arquivo com o código do Plugin.

➜  templates git:(main) ✗ tree
.
├── README.md
└── index.html

0 directories, 2 files

Testar a aplicação do Plugin

1. Use a aplicação criada

Acesse a pasta onde você criou a aplicação, abra o terminal e então execute (sem chaves “< > “) o comando:

stk apply plugin -p <TEXTO-COM-O-CAMINHO-DA-PASTA-DO-PLUGIN>

Exemplo:

stk apply plugin -p /Users/StackSpot.User/hello-stacker/hello-stacker-plugin

Ainda na pasta da aplicação, verifique se o código do arquivo gerado pelo Template foi modificado pelo Plugin. Ao final, teste a sua aplicação, para o exemplo HTML abra o arquivo index.html em um navegador de sua escolha.

Passo 6: Captura de dados nos Inputs do Template e Plugin

Ao criar o Template e Plugin, os inputs essenciais para o seu funcionamento e uso são definidos por padrão. No exemplo do Projeto de páginas HTML, os inputs parecem não ter uma relação direta com o projeto. Será necessário editá-los, para isso, siga os passos abaixo:

  1. Consulte em Configurar arquivos .yaml os tipos obrigatórios e opcionais de inputs e outros atributos;

  2. Na pasta da Stack, acesse a pasta do seu Template e abra o arquivo template.yaml;

  3. Localize o atributo inputs:, você terá os seguintes campos abaixo:

name: hello-stacker-template
description: Template base para uma página HTML.
types:
  - app-template
inputs:
  - label: Project name
    type: text
    name: project_name
    default: project-name
  1. Pule uma linha e adicione o input abaixo:
  - label: Greeting message to use
    type: text
    name: greeting_message
    default: Hello
    items:
      - Hello
      - Whats up
      - Hi
      - Good morning
  1. Ao final, salve as alterações no arquivo template.yaml.

Para o exemplo, não será necessário adicionar ou utilizar inputs no arquivo plugin.yaml. Faça as seguintes alterações:

  1. Na pasta da Stack, acesse a pasta do seu Plugin e abra o arquivo plugin.yaml;
  2. Delete todos os campos com exceção dos campos obrigatórios conforme o exemplo abaixo:
name: hello-stacker-plugin
description: Plugin que adiciona em uma página HTML um script para perguntar o nome de quem acessa a página.
types:
  - app
  1. Ao final, salve as alterações no arquivo plugin.yaml.

Teste os inputs

Após editar os inputs, crie uma nova aplicação de teste e observe as suas mudanças. Se desejar, consulte os passos abaixo:

  1. Criar uma aplicação de teste da seção Testar o Template;
  2. Use a aplicação criada em Testar a aplicação do Plugin.

As alterações desse exemplo irão refletir na aplicação do Template ao criar uma aplicação, confira a imagem abaixo:

Passo 7 (Opcional). Criar um novo Stackfile

Uma Stack pode conter mais de um Template e Plugin, se for o seu caso, para facilitar o uso da Stack para criar aplicações, é opcional usar um Stackfile customizado. O Stackfile descreve uma a combinação de um Template e um ou mais Plugins dentro de uma Stack para serem aplicados em conjunto ao criar uma aplicação.

Dessa forma, o Stackfile possibilita especializar o uso da Stack com essa combinação. Dentro da sua Stack, a pasta stackfiles é gerada por padrão e, dentro dela, o Stackfile default.yaml.

Se não houver a necessidade de disponibilizar um Stackfile customizado, então nenhuma ação é necessária, caso contrário, siga os passos abaixo para criar um novo Stackfile:

  1. Para criar um novo Stackfile, entre na pasta stackfiles e execute o comando abaixo:
stk create stackfile <TEXTO-COM-O-NOME-DO-STACKFILE>

Exemplo:

stk create stackfile hello-stacker-ask-name

Descreva a especialidade que o Stackfile vai adicionar na Stack. Prencha o campo Description:

➜  stackfiles git:(main) ✗ stk create stackfile hello-stacker-ask-name
? Description:  (Describe your stackfile explaining its purpose) Exemplo em HTML que aplica o template hello-stacker-template e o plugin hello-stacker-plugin, para gerar páginas em HTML com um script que pergunta o nome de quem acessa a página.
  1. Na mesma pasta, abra o arquivo do Stackfile criado anteriormente para informar o Template, Plugins e Inputs. Para o exemplo, edite o Stackfile hello-stacker-ask-name.yaml conforme o exemplo abaixo:
type: app
description: Exemplo em HTML que aplica o template hello-stacker-template e o plugin hello-stacker-plugin, para gerar páginas em HTML com um script que pergunta o nome de quem acessa a página.
template: hello-stacker/hello-stacker-template
plugins:
  - plugin: hello-stacker/hello-stacker-plugin

Consulte como criar um stackfile para ver todas opções disponíveis.

Próximos passos

Leia também

Confira os comandos utilizados nesse passo a passo.

Aprenda sobre os comandos relacionados à criação de uma Stack:

Aprenda a editar os inputs dos arquivos .yaml da sua Stack: