Uma vez que o Cordova tenha sido instalado no computador via NPM, o primeiro passo para criar um novo projeto é executar no terminal/prompt de comandos o comando cordova create, cujos detalhes da sintaxe e funcionamento você verá neste documento.

cordova create

O comando cordova create tem por objetivo criar um novo projeto Cordova. Quando executado ele gera a estrutura de pastas e arquivos necessária para iniciar uma nova aplicação.

A sintaxe desse comando é a seguinte:

cordova create <diretório> [id] [nome] [configurações] [opções]

Como podemos ver, esse comando espera os seguintes parâmetros:

  • diretório: Parâmetro obrigatório que indica o diretório em que o projeto será criado. Caso o diretório ainda não exista, ele será criado. Caso o diretório exista e esteja vazio, ele será usado normalmente e dentro dele serão adicionadas outras pastas e arquivos. Já se o diretório existir e não estiver vazio o Cordova retornará o seguinte erro e o projeto não será criado:
    Error: Path already exists and is not empty: <diretório>

  • id: Identificador da aplicação no formato reverse-domain. Esse identificador será salvo no arquivo config.xml, no elemento <widget>, e caso não seja informado assumirá o valor padrão io.cordova.hellocordova. Apesar de ser possível alterar esse valor posteriormente é aconselhado informá-lo já ao executar o comando create, pois ele será usado para gerar os pacotes da linguagem Java para Android, por exemplo.
    Nota: Formato reverse-domain
    A notação reverse-domain, também chamada de reverse-DNS, consiste em nomear os componentes do sistema na forma de domínios web invertidos, normalmente contendo o nome da empresa/desenvolvedor e do projeto. Por exemplo, a empresa DevMedia, que possui o domínio devmedia.com.br, poderia usar o seguinte nome ao criar um projeto chamado MeuAplicativo: br.com.devmedia.MeuAplicativo. Essa notação é muito utilizada em projetos Java, mas também é adotada em outras linguagens.
  • nome: Esse é o título da aplicação e também fica salvo no arquivo config.xml. Caso esse parâmetro não seja informado, ele assumirá o valor padrão HelloCordova. No entanto, é aconselhado informar o nome do projeto no momento da sua criação.
  • opções: Nesta última parte do comando podemos passar ainda o argumento nomeado --template, cujos detalhes são apresentados abaixo:
    --template

    Usado para criar o projeto baseado em um template customizado e que esteja localizado em uma pasta do computador, no NPM ou no GitHub.

    Exemplos:

    • --template=projetos/templates/meu-template (diretório local)
    • --template=template-no-npm (pacote do NPM)
    • --template=https://github.com/usuario/template-cordova (URL do GitHub)
    Nota: para utilizar templates do NPM ou GitHub é necessário que o computador esteja conectado à internet.
    Nota: o valor desses parâmetros pode ser atribuído com o sinal de igualdade, como foi demonstrado acima, ou apenas separando-o por espaço do nome do parâmetro, da seguinte forma: --template meu-template.

Estrutura do projeto

Quando executamos o comando cordova create sem informar um template específico é criada uma estrutura padrão de pastas e arquivos, como mostra a Figura 1.

Estrutura básica de um projeto Cordova
Figura 1. Estrutura básica de um projeto Cordova

Temos então as seguintes pastas e arquivos:

  • hooks: Hooks são scripts que podem ser usados para customizar os comandos do Cordova. Por exemplo, podemos efetuar alguma ação após executar o comando run, como criar ou modificar um arquivo. Os hooks são escritos em JavaScript e devem ser adicionados nessa pasta;
  • platforms: Para desenvolver a aplicação nós devemos trabalhar nos arquivos da pasta www. Porém, quando a aplicação é compilada os arquivos são copiados para a pasta de cada plataforma (iOS, Android, Browser, etc), que fica dentro da pasta platforms. Além disso são gerados também os arquivos específicos de cada plataforma (projeto do XCode para iOS e estrutura de arquivos para o Android Studio, por exemplo);
  • plugins: Algumas funcionalidades comuns na criação de aplicações, como a exibição de mensagens para o usuário, estão disponíveis na forma de plugins. Nessa pasta são adicionados os plugins do Cordova instalados no projeto;
  • res: Nessa pasta ficam recursos de imagem, vídeo, ícones, etc. Esses arquivos são divididos de acordo com a plataforma, o que nos permite customizar a aparência da aplicação nas diferentes plataformas;
  • www: Essa é a pasta em que ficam contidos os arquivos HTML, CSS e JavaScript nos quais trabalharemos. Os arquivos dessa pasta são também copiados para a pasta de cada plataforma quando compilamos a aplicação;
  • .npmignore: Esse é um arquivo do NPM (Node Package Manager) e nele são listados quais arquivos deve ser ignorados quando gerarmos um pacote do NPM a partir da nossa aplicação. Esse pacote é gerado quando temos a intenção de distribuir essa aplicação no repositório do NPM (por exemplo, quando criamos um template para o Cordova e desejamos distribuí-lo);
  • config.xml: Arquivo de configuração principal do projeto Cordova. Nele estão registradas informações sobre o projeto, plugins e plataformas instaladas,etc;
  • package.json: Esse também é um arquivo próprio do NPM e também possui informações sobre o projeto. Essas porém são usadas na instalação de novos pacotes via NPM, bem como se desejarmos publicar a aplicação como um pacote no repositório do NPM.
Nota: Caso utilizemos o parâmetro --template outras pastas e arquivos podem ser criados de acordo com o template.

Exemplos práticos

A seguir temos alguns exemplos práticos de uso do comando cordova create:

cordova create MeuApp 

Cria um projeto no diretório MeuApp com o nome HelloCordova e o id io.cordova.hellocordova.

cordova create MeuApp br.com.devmedia.MeuApp “Meu Aplicativo”

Cria um projeto no diretório MeuApp com o nome “Meu Aplicativo” e o id br.com.devmedia.MeuApp.

cordova create MeuApp br.com.devmedia.MeuApp “Meu App” --template=cordova-phaser-ts-jed

Cria um projeto com as mesmas informações do comando anterior, porém dessa vez se baseando no template cordova-phaser-ts-jed que encontra-se hospedado no repositório do NPM.