Concrete Logo
Hamburger button

Como criar um projeto Open Source em JavaScript

  • Blog
  • 25 de Novembro de 2015
Share

Post originalmente publicado no Medium pessoal do autor. Confira aqui.

Muitos desenvolvedores, tanto iniciantes quanto avançados, ficam na dúvida de como criar (e publicar) um projeto Open Source usando JavaScript. Nesse post vou mostrar o passo-a-passo de como fazer uma lib bem simples em AngularJS e como publicá-la seguindo as melhores práticas usando GitHub, Bower, NPM e Gulp.

1-J5nG2kRBc01_vV0Hl1l7xA

Obs.: Se você não entende muito de AngularJS, não fique preocupado. O foco desse post não é o Angular em si e suas características, mas sim o passo-a-passo de como publicar um projeto Open Source em JavaScript. Se você quiser saber mais sobre AngularJS, dê uma olhada nesse link aqui.

1. Começando o projeto

O projeto se chamará ngLib e não fará nada demais. Será apenas uma diretiva com um console.log dentro. Primeiramente vamos criar uma pasta na qual ficará o projeto ngLib:

Agora precisamos usar o Bower para adicionar as dependências do projeto e garantir que futuramente outras pessoas possam utilizar a lib.

Agora, o Bower vai fazer algumas perguntas para auxiliar na criação do bower.json. Eu prefiro simplesmente aceitar todos os defaults e depois modificar diretamente no arquivo. Após aceitar os defaults, seu arquivo ficará mais ou menos assim:

Editando diretamente o arquivo, vamos deixá-lo assim:

Repare na linha em negrito acima. Como é um projeto em AngularJS, uma das dependências do projeto é o próprio Angular. Pode parecer óbvio, mas muitos desenvolvedores se esquecem desse detalhe. Agora precisamos iniciar o git no projeto para podermos hospedá-lo futuramente no GitHub:

Agora basta adicioná-lo no GitHub. Se você ainda não sabe como fazer isso, use esse tutorial.

1-RxgAzUg2OCfXc-2oH9QMrA

Para que possamos iniciar o desenvolvimento da nossa diretiva, precisamos baixar as dependências que colocamos no Bower (no caso apenas o próprio AngularJS, como falado anteriormente):

Esse comando gera uma pasta chamada bower_components dentro do projeto. É uma boa prática que essa pasta não esteja versionada no git, então vamos criar o arquivo .gitignore para que a pasta não seja considerada nos commits.

Agora adicione a seguinte linha no arquivo .gitignore:

Pronto, agora é só commitar essa mudança e pushar para o GitHub:

2. Criando a Diretiva

Já temos a estrutura mínima montada, então podemos enfim colocar a mão na massa e criar nossa diretiva:

Vamos entrar no arquivo que acabamos de criar e preencher com o código:

Com isso, já temos uma primeira versão funcional do nosso projeto. Falta apenas atualizar nosso bower.json, indicando uma mudança na versão:

Também precisamos registrar a aplicação no index de busca do Bower para que outros desenvolvedores consigam procurar e utilizar nossa lib. É bem simples fazer isso, basta digitar o comando:

Ou então seguir esse tutorial.

bower

Para fechar, vamos commitar essas mudanças e adicionar uma tag do projeto no GitHub:

3. Refinando o projeto

Apesar de o projeto estar funcional, ele ainda pode ser otimizado. Uma boa prática é minificar os arquivos para que os usuários tenham uma renderização mais efetiva da nossa lib no browser.

Vamos fazer todo esse processo utilizando o Gulp.
Uma pequena observação: se você já utiliza o Grunt e está acostumado com ele, não se sinta forçado a mudar para o Gulp. Ambas são excelentes tools. Inclusive há um grupo que prega o uso do próprio NPM como ferramenta de build, que também tem bons argumentos. O meu ponto é: não fique entrando em brigas religiosas pela tecnologia X ou Y. Tente aprender com todas.

O Gulp pode (e deve) ser obtido através do NPM. Para isso vamos criar um package.json de uma forma bem semelhante à que criamos o bower.json:

Da mesma forma, aceite todos os defaults e vamos mudar diretamente o arquivo package.json, para que fique parecido com isso:

Agora sim podemos instalar o Gulp (e, de quebra, alguns plugins dele):

Se verificarmos novamente o package.json, notaremos que ele foi atualizado automaticamente levando em consideração as novas dependências do Gulp:

Podemos agora rodar o Gulp, já que ele está instalado.

Vamos usá-lo para:
1. Pegar o conteúdo da diretiva e minificá-lo;
2. Renomear para ng-lib.min.js (que é uma convenção);
3. Enviar esse arquivo para a pasta dist/ (outra convenção);
4. No final do processo notificar no terminal que tudo deu certo.

gulp

Primeiro vamos criar o gulpfile:

Agora vamos modificá-lo para fazer todos os passos citados anteriormente:

Agora basta rodar:

Se você conseguiu visualizar a mensagem ‘Build finalizado!’ no terminal, você verá que foi criada uma pasta dist/ e dentro dela o arquivo ng-lib.min.js com o conteúdo da diretiva minificado.

Agora só falta criar um README.md que é o ponto de entrada da nossa lib, para que os desenvolvedores possam entender melhor como instalar e a usar. Você pode tomar como exemplo esse README que eu usei em um projeto meu.

Chegamos agora em um ponto bom o suficiente para publicarmos nossa lib e qualquer desenvolvedor possa usá-la (sim, testes unitários poderiam ser adicionados, mas isso vai ficar para um post futuro).

Se você quiser um exemplo real, bem simples e parecido com o desse post, sugiro que dê uma olhada no ngValid. Espero que tenha gostado do post, e se gostou, por favor Recomende/Compartilhe para que mais desenvolvedores possam aprender também! Se ficou alguma dúvida ou tem alguma observação, deixe seu comentário abaixo.