Criando o primeiro aplicativo Ionic: projeto, build e execução

O que você vai fazer neste capítulo

Você vai criar um projeto Ionic do zero, escolher um template inicial (blank ou tabs), executar no navegador em modo de desenvolvimento com hot reload, conhecer scripts comuns (start, build, test e limpeza de cache) e aprender a ler logs para identificar erros de compilação e de runtime.

Criando um projeto Ionic do zero

1) Criar o app com o template adequado

O comando base para criar um projeto é:

ionic start nome-do-app template [opções]

Os templates mais comuns para começar são:

• blank: projeto mínimo, ideal quando você quer construir a navegação e as telas do zero.
• tabs: já vem com navegação por abas e rotas configuradas, ideal para apps com seções fixas (ex.: Início, Busca, Perfil).

Critérios de escolha: blank vs tabs

Exemplos de criação

Opção A: projeto “blank”

ionic start meu-primeiro-ionic blank

Opção B: projeto “tabs”

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

ionic start meu-primeiro-ionic tabs

Após criar, entre na pasta do projeto:

cd meu-primeiro-ionic

Executando no navegador (modo desenvolvimento)

Rodar o servidor de desenvolvimento

Para executar no navegador com recarregamento automático:

ionic serve

O comando inicia um servidor local e abre o app no navegador. Ele também fica observando mudanças nos arquivos para atualizar a aplicação.

Entendendo o fluxo de hot reload

O hot reload (recarregamento durante o desenvolvimento) funciona assim:

• Você altera um arquivo (por exemplo, uma página, componente ou estilo).
• O bundler recompila apenas o necessário (incremental rebuild).
• O navegador atualiza a aplicação automaticamente. Dependendo da mudança, pode ser:
• Atualização de estilo (CSS) quase instantânea, muitas vezes sem recarregar a página inteira.
• Atualização de código (TypeScript/HTML) que pode recarregar a rota atual ou a página inteira.

Na prática, isso reduz o ciclo “editar → salvar → ver resultado”.

Executar em porta específica e sem abrir o navegador

Em alguns cenários (ex.: usar um navegador já aberto, ou rodar em ambiente remoto), você pode ajustar:

ionic serve --port 8101 --no-open

Simular modo mobile no navegador

Você pode testar visualmente como se fosse um dispositivo móvel usando o modo responsivo do DevTools do navegador. Além disso, o Ionic oferece um modo de laboratório para visualizar múltiplas plataformas lado a lado:

ionic serve --lab

Isso ajuda a comparar rapidamente diferenças de estilo entre iOS e Android (quando aplicável ao tema/estilos do projeto).

Build: gerando uma versão compilada do app

Build para produção (web)

Para gerar os arquivos finais otimizados (minificados e prontos para deploy web), use:

ionic build

Esse comando cria uma pasta de saída (geralmente www ou dist, dependendo da configuração do projeto) com os assets compilados.

Quando usar build em vez de serve

• ionic serve: desenvolvimento, hot reload, feedback rápido.
• ionic build: validar se o projeto compila “de verdade” para distribuição, pegando erros que às vezes não aparecem no fluxo de dev.

Scripts comuns do projeto (package.json)

Projetos Ionic (com Angular/React/Vue) costumam expor scripts no package.json. Você pode rodá-los com npm run <script> (ou yarn/pnpm, se estiver usando). Alguns exemplos típicos:

Iniciar desenvolvimento

npm run start

Em muitos projetos, start é equivalente a ionic serve ou chama o comando do framework por baixo.

Build

npm run build

Normalmente chama ionic build ou o build do framework.

Rodar testes

npm test

O comportamento depende do template e do stack (Angular/React/Vue). Se o projeto tiver testes configurados, esse comando executa a suíte.

Ver scripts disponíveis

Abra o package.json e procure a seção scripts:

{  "scripts": {    "start": "...",    "build": "...",    "test": "..."  }}

Isso é útil porque nem todo template vem com os mesmos scripts.

Limpando cache e resolvendo problemas comuns de dependências

Quando você encontra erros estranhos após atualizar dependências, trocar de branch ou interromper instalações, pode ser necessário limpar caches e reinstalar.

1) Reinstalação limpa de dependências

Passo a passo (genérico e muito usado):

# 1) apagar dependências instaladas e lockfile (ajuste conforme seu gerenciador)rm -rf node_modulesrm -f package-lock.json# 2) limpar cache do npm (opcional, mas útil em casos persistentes)npm cache verify# 3) reinstalarnpm install

Se você usa yarn ou pnpm, o lockfile será diferente (yarn.lock, pnpm-lock.yaml).

2) Limpar artefatos de build

Se o build estiver “preso” em resultados antigos, limpe a saída e gere novamente:

ionic build

Em alguns projetos, a pasta de saída pode ser removida manualmente antes do build (ex.: www ou dist), mas faça isso apenas se você souber qual é a pasta correta no seu projeto.

Como ler logs e identificar erros

Dois tipos principais de erro: compilação vs runtime

• Erros de compilação: acontecem durante o build/serve (TypeScript, template, bundler). Geralmente impedem o app de subir ou de atualizar.
• Erros de runtime: acontecem com o app já rodando (ex.: ao clicar em um botão, navegar para uma rota, consumir uma API).

Onde olhar primeiro

• Terminal onde você rodou ionic serve ou ionic build: mostra erros de compilação, warnings e stack traces do bundler.
• Console do navegador (DevTools): mostra erros de runtime, logs de console.log, falhas de rede e exceções.
• Aba Network do DevTools: útil para erros de API, CORS, 404/500, timeouts.

Interpretando erros de compilação (exemplos típicos)

1) Erro de TypeScript

TS2322: Type 'string' is not assignable to type 'number'.

Como agir:

• Leia o código do erro (ex.: TS2322) e a mensagem.
• Localize o arquivo e a linha indicados no log.
• Corrija o tipo (converter, ajustar interface, validar entrada).

2) Módulo não encontrado

Cannot find module 'xyz' or its corresponding type declarations.

Como agir:

• Verifique se a dependência está no package.json.
• Instale o pacote faltante.
• Confirme se o import está correto (nome do pacote/caminho).

3) Erro de template (dependendo do framework)

Template parse errors: Can't bind to '...' since it isn't a known property of '...'

Como agir:

• Verifique se o componente/módulo foi importado/registrado corretamente.
• Confirme se a propriedade existe e está com o nome correto.

Interpretando erros de runtime (exemplos típicos)

1) Undefined/Null em tempo de execução

TypeError: Cannot read properties of undefined (reading 'x')

Como agir:

• Veja a stack trace no console e clique no arquivo/linha.
• Identifique qual variável está undefined e por quê (carregamento assíncrono, rota sem parâmetro, resposta de API inesperada).
• Adicione validações e estados de carregamento (ex.: checar existência antes de acessar).

2) Erros de navegação/rota

ERROR Error: Uncaught (in promise): Error: Cannot match any routes. URL Segment: '...'

Como agir:

• Confirme se a rota existe na configuração de rotas.
• Verifique se o caminho usado na navegação está correto (maiúsculas/minúsculas, parâmetros).

3) Falhas de rede

Failed to fetch

Como agir:

• Abra a aba Network e veja status code, URL e resposta.
• Confirme se a API está acessível e se a URL está correta.
• Se houver CORS, o console costuma indicar bloqueio; ajuste o backend/proxy conforme necessário.

Dicas práticas para depuração rápida

• Leia de baixo para cima em alguns logs: a causa raiz pode aparecer antes de mensagens secundárias.
• Copie o trecho principal do erro (código TS, mensagem e linha) para localizar rapidamente o ponto exato.
• Reduza o problema: comente partes do código para isolar o componente/rota que dispara o erro.
• Use logs estratégicos: registre entradas/saídas de funções e valores críticos antes da linha que quebra.