Pular para o conteúdo principal

Criar Aplicação

Este guia oferece uma visão geral da configuração inicial, abordando o frontend, o banco de dados e o serviço de API. Criaremos uma nova aplicação fullstack de forma rápida e prática.

Introdução​

Embora a plataforma seja poliglota e suporta diversas linguagens de programação, focaremos exclusivamente no uso do JavaScript neste tutorial. Como resultado, criaremos uma aplicação prática que consiste em um formulário exibido em uma janela modal (pop-up) com a funcionalidade de exportação de dados para PDF.

Pré-requisitos​

Antes de iniciar, certifique-se de que possui:

  • A plataforma Netuno previamente instalada em sua máquina. Caso tenha dúvidas nesta etapa, consulte o guia Instalação da plataforma.

  • Acesso ao terminal ou prompt de comando do ambiente de desenvolvimento.

Criar uma Nova Aplicação​

Siga as instruções abaixo para inicializar sua nova aplicação:

Abra o terminal e navegue até a pasta raiz onde o Netuno foi instalado.

Execute o comando de criação da aplicação:

./netuno app

Criação com Parâmetro​

É possível definir o nome da aplicação diretamente na execução do comando, por exemplo:

./netuno app name=minha_aplicacao
Boas Práticas de Nomenclatura

Ao definir o nome da sua aplicação, evite utilizar espaços, acentuações ou caracteres especiais. Prefira o uso de letras minúsculas separadas por hífens ou underscores (exemplo: app-vendas ou gestao_rh) para manter a compatibilidade com URLs e pastas do sistema.

Configuração Inicial​

O assistente de linha de comando fará algumas perguntas para configurar o seu projeto. Informe:

  • Nome da aplicação: O identificador do seu projeto.
  • Tipo de banco de dados: O sistema gerenciador de banco de dados que será utilizado.
  • Idioma: O idioma padrão da interface da sua aplicação.
Dicas e Boas Práticas

Recomendação de Banco de Dados para Iniciantes

Durante o passo a passo, quando for solicitado o tipo de banco de dados, recomendamos escolher a opção H2 Database.

O H2 Database é um banco de dados embutido que já vem integrado ao servidor do Netuno. A grande vantagem é que ele não exige a instalação ou configuração de servidores externos (como PostgreSQL ou MySQL), tornando os desenvolvimentos iniciais e testes muito mais práticos e rápidos.

Comando para Iniciar o Servidor​

Após criar a sua nova aplicação, inicie o servidor da plataforma Netuno. Isso deixará o seu projeto acessível no navegador e pronto para o desenvolvimento contínuo.

Execute o comando abaixo no seu terminal e aguarde a inicialização.

./netuno server app=minha_aplicacao

Ao passar o parâmetro app=minha_aplicacao, o servidor entende que esta será a aplicação padrão a ser executada nesta instância. Com o servidor rodando, já pode começar a editar o seu projeto.

Todos os arquivos e códigos-fonte da sua aplicação ficam armazenados e organizados dentro da pasta 📂 apps/minhaapp.

Credenciais de Acesso (Backoffice)

Ao acessar a interface de administração Backoffice da sua aplicação pela primeira vez, o sistema solicitará autenticação. Para ambientes locais de desenvolvimento, utilize as seguintes credenciais padrão:

Usuário: dev

Senha: dev

Recomendamos alterar essas credenciais ao mover sua aplicação para um ambiente de produção.

Editor de Código​

Para garantir a melhor experiência de desenvolvimento, sugerimos o uso de editores de código modernos, leves e que possuam um bom ecossistema de extensões.

Caso ainda não tenha um editor favorito, recomendamos as seguintes opções gratuitas e amplamente utilizadas pela comunidade:

Nota: Se preferir ferramentas mais robustas e não se importar em investir em licenças, o WebStorm da JetBrains é uma excelente opção premium.

Abra a pasta da aplicação no seu editor:

  • 📂 apps/minha_aplicacao

Todos os arquivos da aplicação ficam armazenados e organizados dentro desta pasta. Todo o desenvolvimento, criação de rotas, lógicas de banco de dados e interfaces visuais acontecerá dentro desta pasta.

Entenda a Arquitetura

Para saber exatamente onde criar cada tipo de arquivo e como o Netuno organiza o backend e o frontend, recomendamos a leitura da documentação detalhada sobre a estrutura de pastas da aplicação:

Consulte o guia: Pastas da Aplicação

Resumo das Etapas​

Com os conhecimentos iniciais do Netuno consolidados, aplicaremos estes conceitos na prática criando uma funcionalidade completa, do início ao fim.

O objetivo prático é adicionar dois novos componentes interativos na interface:

  • Um botão responsável por carregar e exibir o formulário de clientes dentro de uma janela flutuante (Modal).
  • Um botão dedicado a gerar e exportar a lista de clientes cadastrados em um arquivo PDF.

Para alcançar esse resultado com organização e clareza, dividimos o desenvolvimento em uma sequência lógica de etapas. Seguiremos este roteiro:

  • Mapeamento da Interface: Analisar a estrutura de pastas da aplicação para localizar onde o HTML principal do dashboard está definido.

  • Integração com React: Configurar e adicionar a base dos dois novos botões utilizando o framework React no frontend.

  • Lógica da Modal: Construir e programar o comportamento do botão para abrir corretamente o formulário de clientes.

  • Interface de Exportação: Construir e posicionar o botão que acionará o download do arquivo PDF na interface.

  • Desenvolvimento do Serviço (API): Programar o backend criando o serviço que fará a leitura dos dados e a geração dinâmica do arquivo PDF contendo a lista de clientes.

Vamos começar!

Template de Dashboard​

Navegue até a pasta server/templates e abra o arquivo responsável por fornecer o HTML da tela de dashboard.

server/templates/dashboard.html

Ao explorar o código do arquivo dashboard.html, role até o final da página. Encontrará um elemento <div> isolado. É exatamente neste ponto que a plataforma Netuno "injeta" e inicia toda a interface interativa construída em React.

server/templates/dashboard.html
...
<div id="app-dashboard"></div>

Embora o esqueleto HTML fique na pasta server/templates, o desenvolvimento real da interface e a lógica visual não acontecem ali.

Para alterar o comportamento do dashboard ou adicionar novos componentes com React, deverá acessar a pasta dedicada ao desenvolvimento do frontend.

É nesta pasta 📂 ui/ que encontrará os componentes do dashboard e poderá desenvolver as novas funcionalidades visuais da sua aplicação.

Criar Formulário​

Nesta etapa, vamos criar a estrutura de banco de dados necessária para este tutorial: um formulário chamado Cliente contendo um campo de texto chamado Nome.

  • No Backoffice, acesse a área de desenvolvimento clicando no botão Construir (canto superior direito).
  • No menu lateral, navegue até Gestão > Formulários e crie o novo formulário com o Título: Cliente.
  • Clique em Salvar.

O Nome da tabela será preenchido automaticamente com cliente (mantenha em minúsculas, conforme recomendado para bancos de dados).

Consulte o Guia

Caso tenha dúvidas sobre as configurações avançadas desta tela, consulte a documentação completa em Formulários.

Criar Campo​

Com o formulário criado, ele aparecerá no menu lateral esquerdo na categoria Campos.

  • Clique em Cliente para adicionar uma nova coluna:
  • Insira o texto "Nome" no Título do Campo.
  • Selecione o tipo de dados como "text" no campo Tipo.
  • Marque as opções Permitir Filtrar (para habilitar a pesquisa) e Exibir no Resultado (para aparecer na tabela).
  • Clique em Salvar.
Consulte o Guia

Para entender todos os tipos de dados disponíveis e suas propriedades, acesse a documentação detalhada em Campos.

Inserir Dados de Teste​

Para que possamos testar a exportação de PDF nas próximas etapas, precisamos de dados reais no sistema.

  • Clique no botão Visualizar (canto superior direito) para retornar ao Backoffice de uso da aplicação.
  • Acesse o menu Cliente recém-criado na lateral.
  • Utilize o botão + Adicionar para cadastrar alguns clientes de teste no sistema.
  • Clique em Salvar.

Consultar Base de Dados​

O Netuno oferece uma ferramenta integrada que permite executar comandos SQL diretamente no banco de dados da sua aplicação. Tornando-se essencial para realizar consultas rápidas, validar informações ou manipular dados do sistema de forma ágil.

Para acessar a interface de consultas e executar seus comandos, siga os passos abaixo:

  • Na interface principal, acesse a área de desenvolvimento clicando no botão Construir.
  • No menu lateral de navegação, localize a seção Gestão.
  • Clique na opção Query para abrir o console de banco de dados.
  • No editor de texto que aparecerá na tela, digite o comando SQL que deseja executar.
  • Confirme a execução do comando.

Execute o comando abaixo para consultar os clientes cadastrados:

SELECT * FROM cliente

Quando terminar as consultas e desejar retornar à interface de usuário do sistema (backoffice), basta clicar no botão Visualizar.

Adicionar Botões com React​

Nesta etapa, vamos configurar o arquivo principal do painel dashboard para exibir dois novos botões.

Na arquitetura de interface, utilizamos o conceito de Containers para definir áreas abrangentes do sistema, que englobam funcionalidades maiores e agrupam múltiplos componentes menores.

  • No seu editor de código, navegue até a pasta de containers em 📂 ui/src/containers.

  • Localize e abra o arquivo principal do dashboard: 📂 DashboardContainer/index.jsx.

  • Insira o código de importação e renderização dos componentes conforme o exemplo abaixo.

ui/src/containers/DashboardContainer/index.jsx
import { Space } from 'antd';

import BotaoClienteModal from '../../components/BotaoClienteModal';
import BotaoPDF from '../../components/BotaoPDF';

import "./index.less";

function DashboardContainer() {
    return (
        <div className="my-dashboard">
            <Space>
                <BotaoClienteModal />
                <BotaoPDF />
            </Space>
        </div>
    );
}

export default DashboardContainer;

Observe que estes arquivos de botões ainda não existem fisicamente no seu projeto. Como eles são componentes menores e reutilizáveis, criaremos dentro da pasta de componentes dedicados.

Organização de Arquitetura

Mantenha sempre a separação entre Containers (áreas de escopo amplo, como páginas inteiras ou dashboards) e Components (elementos isolados de interface, como botões e modais). Isso torna seu código no Netuno muito mais limpo, fácil de dar manutenção e escalável.

Botão para Formulário​

Acesse a pasta ui/src/components/ e crie uma nova pasta chamada BotaoClienteModal.

Dentro da pasta BotaoClienteModal, crie o arquivo principal do componente nomeado como index.jsx.

📂 ui/src/components/BotaoClienteModal/index.jsx

Abra o arquivo e insira o código abaixo:

ui/src/components/BotaoClienteModal/index.jsx
import { Button } from 'antd';

function BotaoClienteModal() {
    const onClick = () => {
        netuno.modal.create({
            name: 'cliente',
            callback: function (modal) {
                let form = modal.find('[netuno-form]');

                form.on('netuno:new', () => {
                    console.log('Criando um novo Cliente.');
                });

                form.on('netuno:save', () => {
                    netuno.modal.hide(modal)
                    console.log('Salvou um Cliente.');
                });

                form.on('netuno:delete', () => {
                    netuno.modal.hide(modal)
                    console.log('Removeu um Cliente');
                });

                form.on('netuno:back', () => {
                    console.log('Clicou em voltar');
                });

                netuno.loadForm(form);
                netuno.modal.show(modal);
            }
        });
    };
    return (
        <div>
            <Button type="primary" onClick={ onClick }>
                Abrir Formulário do Cliente
            </Button>
        </div>
    );
}

export default BotaoClienteModal;

Entendendo o Código​

A mágica deste componente acontece dentro da função onClick, que utiliza as ferramentas globais de interface do Netuno:

  • netuno.modal.create(): Este método é responsável por instanciar a janela modal na tela e vincular o formulário desejado a ela (neste caso, o formulário chamado cliente).

  • Eventos de Formulário (form.on): O bloco callback nos permite "escutar" (listen) as ações do usuário. Podemos disparar ações customizadas quando o usuário cria um registro (netuno:new), salva (netuno:save), deleta (netuno:delete) ou clica em voltar (netuno:back).

  • netuno.modal.hide() / show(): Métodos utilizados para esconder a modal após uma ação de sucesso ou exibi-la assim que o formulário for carregado.

Integração Concluída

Agora que o componente BotaoClienteModal foi criado com sucesso, a importação que fizemos anteriormente no seu DashboardContainer passará a funcionar sem erros, e o botão já deve ser renderizado na sua tela!

Botão para Exportar PDF​

Nesta etapa, criaremos o segundo botão do Dashboard: o Botão para Exportar PDF.

A principal função deste componente na interface é atuar como um acionador, ou seja, ao ser clicado, ele fará uma requisição para um serviço de backend, responsável por processar os dados do sistema e gerar o arquivo PDF contendo a lista de clientes cadastrados.

  • Acesse a pasta ui/src/components/ e crie uma nova pasta chamada BotaoPDF.

  • Crie um arquivo chamado index.jsx dentra da pasta.

ui/src/components/BotaoPDF/index.jsx

Abra o arquivo e insira o código abaixo:

ui/src/components/BotaoPDF/index.jsx
import { Button } from 'antd';

function BotaoPDF() {
    return (
        <div>
            <Button
                type="primary"
                href="/services/cliente/exporta-pdf"
                target="blank">
                Exportar PDF
            </Button>
        </div>
    );
}

export default BotaoPDF;

Com a criação do componente BotaoPDF, ambos os botões declarados no seu DashboardContainer estão prontos.

Próximos Passos

A estrutura visual e os componentes estão concluídos. Compile o frontend para testar a renderização da interface.

A construção do serviço de backend que efetivamente gerará o PDF será abordada na próxima etapa.

Compilar Frontend​

Os navegadores de internet não compreendem nativamente códigos escritos em React arquivos .jsx ou .tsx e pré-processadores de CSS como .less. Para que a sua interface funcione corretamente, é necessário passar por um processo de compilação (build). Esse processo traduz, empacota e otimiza todo o seu código para arquivos estáticos finais (JavaScript e CSS padrão) que o navegador consegue processar com máxima eficiência.

Pré-requisitos​

Antes de iniciar a compilação, certifique-se de que:

  • Possui o terminal ou prompt de comando aberto no seu ambiente de desenvolvimento.

  • O gerenciador de pacotes Bun está instalado corretamente no seu sistema.

Exemplos de Compilação​

O Netuno disponibiliza diferentes comandos dependendo da etapa do seu desenvolvimento. A partir da pasta raiz do Netuno, navegue até a pasta ui do seu aplicativo.

Execute os comandos dentro da pasta da interface da sua aplicação: 📂 apps/minhaapp/ui

Compilação de Produção​

Realiza a compilação completa e otimizada dos arquivos. É o comando ideal para quando finalizar o desenvolvimento de uma tela ou componente e deseja gerar os arquivos finais leves e com melhor performance.

bun run build

Compilação de Desenvolvimento​

O comando watch realiza uma compilação rápida e fica observando a pasta. Sempre que salvar um arquivo no seu editor, o terminal executa a compilação automaticamente.

bun run watch

Independentemente do comando utilizado build ou watch, as alterações não aparecem instantaneamente na tela do usuário. Atualize a página do backoffice no seu navegador para carregar os novos arquivos gerados.

Monitoramento de Erros e Depuração

Durante o desenvolvimento, erros podem acontecer em duas etapas diferentes. Saiba onde procurá-los:

  • Erros de Compilação: Falhas de sintaxe no código React ou variáveis não declaradas serão apresentadas diretamente no seu terminal, onde o comando bun está em execução.

  • Erros de Execução: Falhas que ocorrem durante o uso da aplicação serão apresentadas no console do navegador. Lembre-se sempre de inspecionar a página para verificar se há algum alerta ou erro.

Compilação Integrada​

O recurso de compilação integrada, permite executar comandos de terminal automaticamente junto com a inicialização do servidor. Isso otimiza o fluxo de trabalho, consolidando todos os logs e monitoramentos em um único terminal central.

Para ativar a compilação integrada, é necessário modificar as configurações de desenvolvimento do seu aplicativo:

  • Acesse a pasta raiz da sua aplicação.

  • Abra o arquivo de configuração de desenvolvimento: _development.json.

  • Localize o bloco de código referente a "commands".

  • Altere o valor da propriedade "enabled" de false para true.

  • Salve o arquivo.

O seu arquivo _development.json deverá ficar com a estrutura semelhante a esta:

config/_development.json
  ...
  "commands": [{
    "command": "bun run watch",
    "enabled": true,
    "install": "bun install",
    "path": "ui"
  }],
  ...

Para que o Netuno leia o arquivo atualizado e aplique a nova configuração, é necessário reiniciar o servidor:

  • Vá até o terminal onde o servidor do Netuno está sendo executado.

  • Encerre o processo pressionando as teclas CTRL + C simultaneamente.

  • Inicie o servidor novamente, indicando o nome da sua aplicação:

./netuno server app=minhaapp
Terminal Único

Após reiniciar o servidor, observe os logs no terminal. Você notará que o Netuno agora está executando automaticamente os comandos de compilação do frontend bun run watch em segundo plano. A partir de agora, tudo funciona integrado na mesma janela.

Serviço de API para gerar PDF​

Na etapa anterior, configuramos o botão Exportar PDF no frontend com o atributo "href" apontando para o endereço services/cliente/exporta-pdf. No entanto, se clicar nele agora, nada acontecerá. Isso ocorre porque o serviço de API responsável por gerar o arquivo ainda não existe.

Todo o desenvolvimento da API ocorre dentro da pasta 📂 server. Nesta seção, criaremos o script que busca os registros no banco de dados e constrói o documento PDF visualmente.

Pré-requisitos​

  • Ter criado o componente BotaoPDF no frontend apontando para a URL correta.
  • Ter o servidor do Netuno em execução.

O Netuno roteia automaticamente as URLs da sua API com base na estrutura de pastas dentro de server/services/. Para criar o serviço, siga os passos:

  • Navegue até a pasta de serviços do backend: server/services/. Crie uma pasta chamada cliente.

  • Dentro dessa pasta, crie um arquivo chamado exporta-pdf.js.

O Netuno é poliglota. Utilizaremos JavaScript neste exemplo, use a extensão correspondente à linguagem de sua preferência.

Abra o arquivo e insira o código abaixo para gerar a estrutura do seu PDF:

  • server/services/cliente/exporta-pdf.js
server/services/cliente/exporta-pdf.js
_header.contentType("pdf")

const pdfDocument = _pdf.newDocument(_pdf.pageSize("A5"))

pdfDocument.add(
    _pdf.paragraph("Lista de Clientes:")
        .setFontSize(16)
        .setFontColor(_pdf.color("#1abc9c"))
)

const dbClientes = _db.form("cliente").all()

for (const dbCliente of dbClientes) {
    pdfDocument.add(
        _pdf.paragraph(dbCliente.getString("nome"))
            .setFontSize(12)
            .setFontColor(_pdf.color("#748dae"))
    )
}

pdfDocument.close()

Entendendo o Código​

  • _header.contentType("pdf"): Avisa ao navegador que a resposta dessa requisição não é um texto ou JSON comum, mas sim um arquivo PDF.

  • _pdf: É o recurso nativo do Netuno para manipulação de PDFs. Com ele, definimos o tamanho da página (A5), criamos parágrafos, ajustamos tamanhos de fonte (setFontSize) e cores (setFontColor).

  • _db.form("cliente").all(): Consulta o banco de dados e retorna todos os registros salvos no formulário "cliente". O laço de repetição (for) percorre cada um desses clientes e extrai a informação do campo "nome" para imprimir no documento.

  • pdfDocument.close(): Finaliza a construção do documento e o envia como resposta.

Validação e Testes​

Não é necessário clicar no botão do dashboard toda vez que quiser testar o seu serviço. Como se trata de uma requisição simples (GET), poderá validar a execução acessando a URL da API diretamente pelo navegador.

Para este exemplo, acesse o seguinte endereço: http://localhost:9000/services/cliente/exporta-pdf

Se o arquivo PDF for gerado e exibido na tela contendo a lista de clientes, o serviço está funcionando perfeitamente! Consequentemente, o botão Exportar PDF no seu Dashboard passará a funcionar de forma automática.

Rastreamento de Erros no Backend

Se a página ficar em branco ou retornar uma mensagem de erro ao acessar a URL, verifique imediatamente o terminal onde o servidor do Netuno está rodando. Diferente do frontend, cujos erros aparecem no console do navegador, qualquer falha de execução nos scripts da pasta server será exibida detalhadamente no terminal do servidor backend.

Conclusão​

Neste tutorial, você passou por uma jornada prática de desenvolvimento fullstack utilizando o Netuno.

O objetivo principal foi demonstrar como a plataforma integra a construção de interfaces visuais com a robustez do servidor, sempre focando em alta produtividade.

Recapitulando as etapas concluídas:

  • Desenvolvimento de Frontend: customizou o dashboard em React, criando componentes de interface e botões interativos de forma modular.

  • Gestão e Estrutura de Dados: viu como é rápido criar formulários e campos no painel para registrar e manipular informações sem precisar escrever rotinas complexas de persistência.

  • Consultas Diretas: Utilizou o recurso de Query para executar comandos SQL de forma ágil, testando a base de dados.

  • Criação de APIs no Backend: Desenvolveu um serviço para geração de PDF e observou uma das grandes vantagens do Netuno: a atualização a quente (hot-reload). Você não precisa reiniciar o servidor a cada alteração no código do backend, o que agiliza imensamente a programação.

  • Ambiente Otimizado: Configurou a compilação integrada, centralizando os processos do frontend e do backend em um único terminal para manter o foco e evitar distrações.

A plataforma foi projetada desde a sua essência para otimizar e acelerar o desenvolvimento de software. Agora que você compreende o fluxo básico de integração entre low-code e código customizado, você está pronto para construir aplicações muito mais complexas e escaláveis.

Continue explorando as próximas seções da documentação para dominar novos recursos.

O desenvolvimento fica muito mais fácil quando você faz parte de uma comunidade ativa. Acesse os links das redes sociais no rodapé desta página.