Estrutura de pastas

Posted on Ago 03, 2026 by

Projetos criados através da Cordova CLI possuem a seguinte estrutura de pastas por padrão:

myapp/
├── config.xml
├── node_modules/
├── package.json
├── platforms/
├── plugins/
└── www

package.json

Arquivo de manifesto que declara as dependências de pacotes JavaScript utilizadas no projeto, incluindo o Cordova, as plataformas adicionadas e todos os plugins instalados. Variáveis de configuração dos plugins também ficam armazenadas neste arquivo.

Seu projeto já pode ter um package.json nativo com dependências próprias (gerado por um framework frontend, por exemplo). O Cordova apenas acrescenta suas configurações no arquivo, sem interferir em outras ferramentas ou nas dependências já existentes.

{
  "name": "com.foxdevelop.hello",
  "displayName": "HelloWorld",
  "version": "1.0.0",
  "description": "A sample Apache Cordova application that responds to the deviceready event.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "ecosystem:cordova"
  ],
  "author": "Apache Cordova Team",
  "license": "Apache-2.0",
  "devDependencies": {
    "cordova-android": "^15.1.0",
    "cordova-plugin-camera": "^8.0.0"
  },
  "cordova": {
    "platforms": [
      "android"
    ],
    "plugins": {
      "cordova-plugin-camera": {
        "ANDROIDX_CORE_VERSION": "1.6.+"
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)
  1. "name": "com.foxdevelop.hello" Nome do pacote npm. Em projetos Cordova, geralmente coincide com o identificador widget presente no config.xml.

Atenção: esse valor não é o nome de pacote nativo para Android/iOS. O identificador nativo continua sendo controlado pelo atributo id dentro de config.xml.

  1. "displayName": "HelloWorld" Nome amigável para exibição, corresponde ao nome do aplicativo e deve estar alinhado com a tag <name> no config.xml.
  2. "version": "1.0.0" Número de versão do projeto, seguindo o padrão de versionamento semântico versão principal.versão secundária.patch. Recomenda-se manter o mesmo valor da versão definida no config.xml.
  3. "description": "A sample Apache Cordova application that responds to the deviceready event." Descrição do projeto, um metadado exibido no npm, não interfere no empacotamento e execução do aplicativo.
  4. "main": "index.js" Arquivo de entrada seguindo o padrão npm. O Cordova quase não utiliza esse campo, ele é gerado automaticamente pelo modelo e pode ser ignorado. O verdadeiro ponto de entrada web de um app Cordova é o arquivo www/index.html (gerenciado pelo config.xml).
  5. "scripts": { "test": "echo \"Error: no test specified\" && exit 1" } Scripts personalizados do npm. O template vem apenas com o comando test por padrão, sem comandos rápidos para build ou empacotamento. Você pode expandir essa lista depois, como no exemplo:
"scripts": {
  "build-android": "cordova build android"
}
Code language: JavaScript (javascript)
  1. "keywords": ["ecosystem:cordova"] Rótulos de busca para o npm. O marcador ecosystem:cordova classifica o projeto como parte do ecossistema Cordova, serve apenas para buscas no npm e não tem efeito durante a execução.
  2. "author": "Apache Cordova Team" Dados do autor, apenas metainformação.
  3. "license": "Apache-2.0" Licença de código aberto Apache 2.0, a licença padrão oficial do Cordova.

config.xml

Armazena todas as preferências e configurações do aplicativo Cordova, usadas para customizar o comportamento de execução do projeto.

Documentação de referência: Manual oficial do config.xml

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.foxdevelop.hello" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
    <name>HelloWorld</name>
    <description>
        A sample Apache Cordova application that responds to the deviceready event.
    </description>
    <author email="dev@cordova.apache.org" href="https://cordova.apache.org">
        Apache Cordova Team
    </author>
    <content src="index.html" />
    <allow-intent href="http://*/*" />
    <allow-intent href="https://*/*" />
</widget>
Code language: HTML, XML (xml)

id="com.foxdevelop.hello"Identificador único do aplicativo (Bundle ID)

  • Android: Identificador de pacote applicationId
  • iOS: Bundle Identifier

Não altere esse valor arbitrariamente antes de publicar nas lojas! Após a modificação, o sistema reconhecerá como um aplicativo totalmente novo. Padrão recomendado: domínio invertido domínio-da-empresa.nome-do-projeto

version="1.0.0" Número da versão do aplicativo (versionamento semântico major.minor.patch), corresponde à versão final após o empacotamento.

<name>HelloWorld</name>

Nome de exibição do aplicativo, o rótulo visível abaixo do ícone na tela inicial do celular.

<description>

Texto descritivo do aplicativo, lido por algumas plataformas durante o empacotamento e para informações nas lojas de aplicativos.

<author>

Dados do desenvolvedor: e-mail, site oficial e nome do autor. Apenas metadados, não interferem no funcionamento.

<content src="index.html" />

Configuração mais importante

Página inicial carregada ao abrir o aplicativo Cordova.

Quando o app é iniciado, o contêiner carrega diretamente o arquivo www/index.html.

Você pode alterar para src="pages/home.html" para mudar a página de entrada.

<allow-intent>

<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
Code language: HTML, XML (xml)

Objetivo: Permitir que o aplicativo abra páginas externas usando o navegador do sistema

allow-intent ≠ Permitir requisições cross-origin dentro da página.

Muitos desenvolvedores confundem os dois conceitos:

  1. allow-intent: Ao clicar em um link com target="_blank", abre o navegador nativo do celular. Controla quais endereços podem ser abertos dessa forma. A configuração atual permite abrir qualquer endereço http/https no navegador externo.
  2. access origin: Define se o webview interno do app consegue fazer requisições para APIs externas (cross-origin). Essa linha de configuração não existe no exemplo apresentado!

⚠️ Problema comum:

Se suas requisições AJAX dentro da página apresentarem erro de cross-origin, apenas usar allow-intent não resolve. Você precisa adicionar:

xml

<!-- Permite o webview acessar todas as APIs com https -->
<access origin="*" />Code language: HTML, XML (xml)

www/

Pasta onde ficam os recursos web do projeto: arquivos HTML, CSS, JavaScript e todos os recursos estáticos.

Como desenvolvedor de aplicativos Cordova, a maior parte do código e recursos do projeto ficam armazenados aqui. Ao executar o comando cordova prepare, os arquivos desta pasta são copiados para as pastas www de cada plataforma alvo.

A pasta fonte www é sincronizada e copiada para as subpastas de cada plataforma. Exemplos de caminhos:

platforms/ios/www ou platforms/android/assets/www.

A CLI sobrescreve constantemente os arquivos nas pastas das plataformas com base na pasta raiz www. Edite apenas os arquivos dentro da pasta www principal, nunca altere diretamente os arquivos dentro da pasta platforms.

Se você usa ferramentas de build frontend, configure a saída dos arquivos compilados para a pasta www. Se desenvolver diretamente dentro da pasta www, recomendamos incluí-la no controle de versão.

node_modules/

Armazena todos os pacotes JavaScript baixados do repositório npm, incluindo o Cordova, suas ferramentas complementares e todas as dependências declaradas no package.json.

Ao rodar cordova platform add ou cordova plugin add para instalar plataformas ou plugins, os recursos correspondentes são baixados do npmjs e salvos em node_modules/.

Depois disso, o Cordova copia os códigos das plataformas e plugins desta pasta para os locais corretos, garantindo o funcionamento do aplicativo.

Esta pasta também contém os scripts necessários para executar cordova prepare e cordova build e compilar cada plataforma.

⚠️ Importante: node_modules é o diretório de códigos originais das dependências. Não edite nenhum arquivo manualmente aqui. Além disso, não envie essa pasta para o sistema de controle de versões.

Consulte a documentação de padrões de pastas do npmjs para mais detalhes.

platforms/

Contém o código fonte e os scripts de compilação de cada plataforma adicionada ao projeto.

⚠️ Aviso: Ao compilar aplicativos pela CLI, evite alterar qualquer arquivo dentro de /platforms/ a menos que compreenda todo o funcionamento ou a documentação oficial autorize explicitamente.

Os arquivos desta pasta são frequentemente sobrescritos durante o prepare do projeto ou ao reinstalar plugins.

plugins/

Pasta temporária para plugins: os plugins instalados são copiados primeiro para este local, depois implantados nas pastas de cada plataforma.

Não é recomendado adicionar essa pasta ao controle de versões.

Se você desenvolver plugins próprios, customizados internamente ou modificados, não os armazene dentro da pasta plugins.

Regras para controle de versão

Recomenda-se não adicionar platforms/ e plugins/ ao controle de versão, pois são arquivos gerados durante o processo de build.

As plataformas e plugins instalados são registrados automaticamente no package.json. Ao executar cordova prepare, a ferramenta baixa automaticamente as plataformas e plugins necessários.

Pastas opcionais

merges/

Ao criar um projeto Cordova pela CLI, a pasta merges não é criada por padrão. Oficialmente seu uso não é recomendado, mas ela ainda é mantida para compatibilidade.

As subpastas dentro dela servem para guardar recursos web específicos de cada plataforma (HTML, CSS, JS). Durante a etapa prepare, esses arquivos são enviados para o projeto nativo correspondente.

Arquivos dentro de merges/ sobrescrevem arquivos com o mesmo nome na pasta www (apenas para a plataforma correspondente).

Exemplo de estrutura de pastas:

plaintext

myapp/
├── merges
│   ├── android/
│   │   └── android.js
│   └── ios/
│       └── app.js
└── www/
    └── app.js

Após compilar os projetos Android e iOS:

  • Aplicativo Android: contém app.js (vindo da pasta www) + android.js
  • Aplicativo iOS: possui apenas o arquivo app.js, carregado de merges/ios/app.js, substituindo a versão genérica da pasta www

Estrutura de pastas

Posted in Tutorial do Cordova

Deixe um comentário

O seu endereço de email não será publicado. Campos obrigatórios marcados com *