Você não vai acreditar; é muito fácil!

Se você já criou muitos módulos do npm, pode pular essa seção. Se não, vamos fazer uma rápida introdução.

Versão abreviada

Um módulo do npm necessita apenas de um arquivo package.json com as propriedades name e version.

Olá!

Aí está você, apenas um pequeno elefante com a vida toda pela frente. Você não é um mestre em fazer pacotes do npm, mas adoraria saber como, certo? Todos os grandes elefantes andam por aí com suas patas gigantes, fazendo pacotes após pacotes. Você pode pensar:

"Não consigo competir com isso".

Bem, estou aqui para dizer para você que você consegue! Não precisa duvidar da sua capacidade.

Vamos começar!

Você não é um elefante

Entenda o que eu disse como uma metáfora.

Você já se perguntou como elefantes bebês são chamados?

Com certeza, já. Um elefante bebê é um "bebê elefante", oras.

Eu acredito em você

A autossabotagem é real. Acaba ocorrendo que as pessoas deixam de fazer coisas muito legais. Você acha que você não será bem-sucedido. Então, você acaba não fazendo nada, mas exalta as pessoas que fazem coisas incríveis. Isso é muito irônico. Por isso, vou mostrar para você o menor módulo npm possível.

Em breve, você terá várias ideias de módulos npm ao seu alcance, código reutilizável até onde os olhos podem ver – tudo isso sem truques e sem instruções complexas.

As instruções complexas

Eu prometi que eu não usaria instruções complexas, mas usei. Elas, porém, não são tão complexas assim. Você vai me perdoar um dia.

Passo 1: conta do npm

Você vai precisar de uma. É parte do acordo. Crie a conta aqui.

Passo 2: login

Você fez a conta do npm? Já fez? Legal. Também vou assumir que você sabe usar linha de comando/console etc (textos em inglês). Eu vou chamar de terminal a partir de agora. Aparentemente, há uma diferença.

Vá no terminal e escreva:

npm adduser

Você também pode usar o comando:

npm login

Escolha o comando que agrade a você.

Você receberá uma mensagem pedindo seu nome de usuário, senha e e-mail.

A mensagem será parecida com esta:

Logged in as bamblehorse to scope @username on https://registry.npmjs.org/.

Vamos em frente!

Hora de fazer um pacote

Primeiramente, precisamos de uma pasta para colocar nosso código. Crie uma pasta da maneira que se sentir confortável. Eu vou chamar o meu pacote de tiny (palavra em inglês para minúsculo) porque o pacote será, de fato, muito pequeno. Eu adicionei alguns comandos de terminal para aqueles que não estão familiarizados com eles.

md tiny

Nessa pasta, vamos precisar de um arquivo package.json. Se você já usa Node.js, já viu esse arquivo antes. É um arquivo JSON que inclui informações sobre o seu projeto e possui uma infinidade de opções diferentes. Neste tutorial, vamos focar apenas em duas delas.

cd tiny && touch package.json

Qual deve ser o tamanho do pacote?

Muito pequeno.

Todos os tutoriais sobre fazer um pacote npm, inclusive o da documentação oficial, dizem para você adicionar determinados campos no seu package.json. Vamos tentar publicar nosso pacote com o mínimo possível até ele funcionar. Como se fosse um TDD para um pacote do npm mínimo.

Observação: eu estou mostrando isso para demonstrar que fazer um pacote do npm não precisa ser complicado. Para ser útil para a comunidade em geral, um pacote precisa de algumas coisas a mais – e vamos abordar isso mais adiante no artigo.

Publicação: primeira tentativa

Para publicar o seu pacote do npm, você deve executar um comando bem conveniente: npm publish.

Então, temos um package.json vazio na nossa pasta e vamos fazer uma tentativa:

npm publish

Opa!

Recebemos um erro:

npm ERR! file package.json
npm ERR! code EJSONPARSE
npm ERR! Failed to parse json
npm ERR! Unexpected end of JSON input while parsing near ''
npm ERR! File: package.json
npm ERR! Failed to parse package.json data.
npm ERR! package.json must be actual JSON, not just JavaScript.
npm ERR!
npm ERR! Tell the package author to fix their package.json file. JSON.parse

O npm não gostou muito do seu pacote.

Faz sentido.

Publicação: segunda tentativa

Vamos dar um nome para o nosso pacote no arquivo package.json:

{
"name": "@bamblehorse/tiny"
}

Você deve ter percebido que eu adicionei meu username do npm no começo.

Por que fazer isso?

Usando o nome @bamblehorse/tiny ao invés de apenas tiny, criamos um pacote sob o escopo do nosso username. Isso é chamado de scoped package (em português, pacote com escopo). Isso nos permite usar nomes curtos que talvez já foram usados. Por exemplo, o pacote tiny já existe no npm.

Você já deve ter visto isso em bibliotecas populares como a do framework Angular, da Google. Eles possuem alguns scoped packages, como @angular/core e @angular/http.

Bem legal, não?

Vamos tentar publicar uma segunda vez:

npm publish

O erro é menor dessa vez – tivemos um progresso.

npm ERR! package.json requires a valid "version" field

Cada pacote do npm precisa de uma versão para que os desenvolvedores saibam se eles podem atualizar com segurança para uma nova versão do nosso pacote sem quebrar o resto do código deles. O sistema de versionamento do npm é chamado de SemVer, que significa Semantic Versioning (em português, versionamento semântico).

Não se preocupe muito em entender os nomes mais complexos de versão, mas aqui está um resumo de como os mais básicos funcionam:

Dado um número de versão MAJOR.MINOR.PATCH, incremente o:

1. MAJOR quando você faz mudanças incompatíveis na API.

2. MINOR quando você adiciona uma funcionalidade de modo compatível com a versão anterior, e

3. PATCH quando você conserta erros de maneira compatível com a última versão.

Rótulos adicionais para pré-lançamento e metadados de build estão disponíveis como extensões do formato MAJOR.MINOR.PATCH.

https://semver.org

Publicando: terceira tentativa

Vamos colocar no nosso package.json a versão: 1.0.0 – o primeiro lançamento major.

{
"name": "@bamblehorse/tiny",
"version": "1.0.0"
}

Vamos publicar!

npm publish

Ah, droga.

npm ERR! publish Failed PUT 402
npm ERR! code E402
npm ERR! You must sign up for private packages : @bamblehorse/tiny

Permita-me explicar.

Scoped packages são automaticamente publicados de maneira privada, pois, além de serem úteis para usuários únicos como nós, eles também são utilizados por empresas para compartilhar código entre projetos. Se tivéssemos publicado um pacote normal, nossa jornada teria acabado aqui.

Tudo que precisamos mudar é dizer para o npm que, na verdade, queremos que todo mundo possa usar esse módulo – não o manter trancado nos cofres deles. Portanto, executamos o seguinte comando:

npm publish --access=public

De repente, o sucesso!

+ @bamblehorse/tiny@1.0.0

Recebemos um sinal de adição, o nome do nosso pacote e a versão.

Conseguimos — estamos no clube do npm.

Estou animado. Você deve estar animado também.

Você viu?

npm loves you (em português, o npm ama você)

Que fofo!

A primeira versão está disponível no npm!

Seguindo em frente

Se quisermos ser levados a sério como desenvolvedores e se quisermos que nosso pacote seja usado, precisaremos mostrar o código para as pessoas e dizer para elas como elas devem usar. Em geral, fazemos isso colocando nosso código em algum lugar público e adicionando um arquivo readme.

Também precisamos de algum código. É verdade, não temos código ainda.

O Github é um ótimo lugar para colocar o seu código. Vamos fazer um novo repositório.

README!

Eu me acostumei a escrever arquivos README (do inglês "read me" – em português, leia-me) ao invés de readme. Você não tem que fazer isso mais. É uma convenção divertida. Vamos adicionar algumas badges descoladas do shields.io para as pessoas saberem que somos superlegais e profissionais. Aqui está uma que permite as pessoas saberem a versão atual do nosso pacote:‌

A próxima badge é interessante. Ela falhou porque não temos nenhum código, na verdade. Deveríamos, realmente, escrever um pouco de código...

Licença para programar

O título é definitivamente uma referência a James Bond. Na verdade, eu me esqueci de adicionar uma licença. Uma licença permite que as pessoas saibam em quais situações elas podem usar seu código. Há várias licenças diferentes.

Existe uma página legal chamada insights em todo repositório do GitHub onde você pode checar várias estatísticas – incluindo os padrões da comunidade para o projeto. Vou adicionar minha licença por lá.

Então, você vai para esta página:

O código

Ainda não temos um código. Isso é um pouco constrangedor.

Vamos adicionar o código agora antes que percamos toda a credibilidade.

module.exports = function tiny(string) {
  if (typeof string !== "string") throw new TypeError("Tiny wants a string!");
  return string.replace(/\s/g, "");
};

Aí está. Uma função minúscula (do inglês, tiny) que remove todos os espaços de uma string.

Então, tudo que um pacote do npm exige é um arquivo index.js. Esse é o ponto de entrada do seu pacote. Você pode fazer isso de diferentes maneiras à medida que o seu pacote fica mais complexo. Por agora, porém, isso é tudo de que precisamos.

Já chegamos lá?

Estamos bem perto. Provavelmente, deveríamos atualizar nosso package.json minimalista e adicionar algumas instruções ao nosso readme.md. Senão, ninguém saberia como usar nosso belíssimo código.

package.json

{
  "name": "@bamblehorse/tiny",
  "version": "1.0.0",
  "description": "Removes all spaces from a string",
  "license": "MIT",
  "repository": "bamblehorse/tiny",
  "main": "index.js",
  "keywords": [
    "tiny",
    "npm",
    "package",
    "bamblehorse"
  ]
}

Adicionamos:

• description: uma descrição curta do pacote
• repository: compatível com o GitHub — então, você pode escrever username/repo
• license: a licença da MIT, neste caso
• main: o ponto de entrada do pacote, relativo à pasta raiz
• keywords: uma lista de palavras-chave usadas para descobrir seu pacote em uma pesquisa no npm.

readme.md

@bamblehorse/tiny

Removes all spaces from a string.

Install

$ npm install @bamblehorse/tiny

Usage

const tiny = require("@bamblehorse/tiny");

tiny("So much space!");
//=> "Somuchspace!"

tiny(1337);
//=> Uncaught TypeError: Tiny wants a string!
//    at tiny (<anonymous>:2:41)
//    at <anonymous>:1:1

Adicionamos instruções sobre como instalar e usar o pacote. Legal!

Se você quer um bom modelo para seu readme, é só conferir pacotes populares na comunidade de código aberto (do inglês, open source) e usar os formatos deles para começar.

Conclusão

Vamos publicar nosso pacote espetacular.

Versão

Primeiramente, vamos atualizar a versão com o comando npm version.

Esse é um lançamento major. Então, escrevemos:

npm version major

O que nos retorna:

v2.0.0

Publique!

Vamos rodar nosso novo comando favorito:

npm publish

Está pronto:

+ @bamblehorse/tiny@2.0.0

Coisas legais

A Package Phobia dá um ótimo resumo do seu pacote do npm. Você também pode verificar cada arquivo em sites como o Unpkg.

Agradecimento

Foi uma jornada maravilhosa que acabamos de fazer juntos. Espero que você tenha aproveitado tanto quanto eu. Se puder, deixe uma estrela para o pacote que nós acabamos de criar aqui:

★ Github.com/Bamblehorse/tiny ★

Siga o autor no Medium ou no próprio GitHub.

O Next.js tem tido um crescimento constante como uma ferramenta obrigatória para desenvolvedores criarem aplicações em React. Parte do que faz ele bom são as suas APIs de obtenção de dados (em inglês, data fetching) que solicitam dados para cada página. Como, porém, podemos usar essa API para fazer queries do GraphQL para nossa aplicação?

• O que é o GraphQL?
• O que é o Apollo GraphQL?
• Solicitando dados no Next.js
• O que vamos criar?
• Passo 0: Criando uma aplicação do Next.js
• Passo 1: Adicionando o Apollo GraphQL em uma aplicação do Next.js
• Passo 2: Adicionando dados em uma página do Next.js com getStaticProps
• Passo 3: Recuperando dados com uma query do GraphQL em Next.js usando o Apollo Client
• Passo 4: Adicionando dados de lançamento da SpaceX na página

O que é o GraphQL?

O GraphQL é uma query language e runtime que fornece uma maneira de interagir com uma API, diferente daquilo que você esperaria de uma API REST tradicional.

Quando dados são solicitados, ao invés de fazer uma requisição GET para uma URL para pegar esse dado, um endpoint do GraphQL recebe uma "query" (consulta). Essa query indica quais dados queremos recuperar, seja um conjunto de dados completo ou apenas uma parte deles.

Seus dados poder se parecer com isto:

Movie { "title": "Sunshine", "releaseYear": "2007", "actors": [...], "writers": [...] }

Pode ser que você queira apenas pegar o título e o ano em que o filme foi lançado. Para isso, você poderia enviar uma query assim:

Movie { title releaseYear }‌

Isso recuperaria apenas os dados de que você precisa.

A parte legal é que você também pode criar relações complexas entre dados. Com uma única query, você poderia ainda pedir dados de diferentes partes do banco de dados, o que tradicionalmente levaria a múltiplas solicitações para a API REST.

O que é o Apollo GraphQL?

No seu núcleo, o Apollo GraphQL é uma implementação do GraphQL que auxilia a trazer os dados como um grafo.

O Apollo também oferece e mantém um client de GraphQL, que é o que vamos usar. Ele permite a interação programática com uma API do GraphQL.

Usando o client do Apollo GraphQL, seremos capazes de fazer solicitações para uma API do GraphQL de modo similar ao que você esperaria de um client para APIs REST.

Solicitando dados no Next.js

Quando estamos solicitando dados no Next.js, há algumas formas de se recuperar esses dados.

Primeiramente, você poderia fazer o client executar a solicitação quando a página carregar. O problema disso é que você está colocando o fardo no client de achar tempo para fazer essas solicitações.

APIs do Next.js, como getStaticProps e getServerSideProps, permitem que você colete dados em diferentes momentos do ciclo de vida, nos dando a oportunidade de fazer uma aplicação complemente estática (vídeo em inglês) ou que ela seja renderizada do lado do servidor. Essas funções servem os dados que já foram renderizados na página diretamente no navegador.

Usando um desses métodos, somos capazes de solicitar dados juntamente com nossas páginas e de injetar esses dados como props diretamente na nossa aplicação.

O que vamos criar?

Vamos criar uma aplicação do Next.js que mostra os últimos lançamentos da SpaceX.

Utilizaremos a API mantida pela SpaceX Land para fazer uma query do GraphQL que pega os últimos 10 voos. Usando getStaticProps, vamos fazer a solicitação na build, o que significa que nossa página será renderizada estaticamente com nossos dados.

Passo 0: Criando a aplicação do Next.js

Usando Create Next App, podemos rapidamente começar uma nova aplicação do Next.js, que usaremos para navegar no código imediatamente.

No terminal, execute o comando:

npx create-next-app my-spacex-launches

Nota: você não precisa usar my-spacex-app, sinta-se livre para substituir por qualquer nome que você deseje dar para o projeto.

Depois de rodar o script, o Next.js vai configurar um novo projeto e instalar as dependências.

Uma vez terminado, você pode começar o servidor de desenvolvimento:

cd my-spacex-launches
npm run dev

Esse comando iniciará um novo servidor em http://localhost:3000, onde você pode visitar a sua nova aplicação!

Passo 1: Adicionando o Apollo GraphQL em uma aplicação do Next.js

Para começar a fazer uma query do GraphQL, vamos precisar de um client do GraphQL. Vamos utilizar o client Apollo GraphQL para fazer nossas queries para o servidor do GraphQL da SpaceX.

Novamente, no terminal, execute o seguinte comando para instalar as nossas novas dependências:

‌                   npm install @apollo/client graphql

Esse comando vai adicionar o Apollo Client e também o GraphQL, que precisaremos para formar uma query do GraphQL.

Uma vez que a instalação completar, estaremos prontos para começar a usar o Apollo Client.

Acompanhe com o commit!

Passo 2: Adicionando dados a uma página do Next.js com getStaticProps

Antes de solicitarmos dados com o Apollo, vamos configurar nossa página para sermos capazes de requisitar os dados e, então, passar esses dados como props para nossa página na build.

Vamos definir uma nova função no fim da página, embaixo do nosso componente Home, chamada getStaticProps:

export async function getStaticProps() {
  // O código vai aqui
}

Quando o Next.js fizer a build da nossa aplicação, ele saberá onde encontrar essa função. Então, quando a exportamos, estamos informando o Next.js que queremos rodar o código daquela função.

Dentro da nossa função getStaticProps, vamos, em última instância, retornar as props para a página. Para testar isso, vamos adicionar o seguinte na nossa função:

export async function getStaticProps() {
  return {
    props: {
      launches: []
    }
  }
}

Aqui, estamos passando uma nova prop chamada launches e estamos definindo a prop como um array vazio.

Agora, de volta para o nosso componente Home, vamos adicionar um novo argumento desestruturado que servirá como nossa prop e também vamos utilizar o console.log para testá-la:

export default function Home({ launches }) {
  console.log('launches', launches);
}

Se recarregarmos a página, podemos observar que agora estamos imprimindo nossa nova prop launches, que inclui um array vazio da maneira como definimos.

O interessante disso é que, uma vez que a função getStaticProps que estamos definindo é assíncrona, podemos fazer qualquer solicitação que quisermos (incluindo uma query do GraphQL) e retorná-la como props para a nossa página, que é o que veremos mais adiante.

Acompanhe com o commit!

Passo 3: Recuperando dados com uma query do GraphQL no Next.js usando o Apollo Client

Agora que nossa aplicação está preparada para adicionar na nossa página e que temos o Apollo instalado, podemos finalmente fazer uma solicitação para pegar nossos dados da SpaceX.

Aqui, vamos usar o Apollo Client, que é o que permite nos conectarmos com o servidor do GraphQL da SpaceX. Faremos nossa solicitação para a API usando o método getStaticProps do Next.js, nos permitindo criar props dinamicamente para nossa página quando ela é construída.

Primeiramente, vamos importar nossas dependências do Apollo no projeto. No topo da página adicione:

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

Isso incluirá o client do Apollo propriamente dito, InMemoryCache, que permite ao Apollo otimizar por meio de leitura de um cache, e gql, que utilizaremos para formar nossa query do GraphQL.

Agora, vamos utilizar o Apollo Client. Para isso, precisamos configurar uma nova instância dele:

Dentro da função getStaticProps, adicione:

const client = new ApolloClient({
  uri: 'https://api.spacex.land/graphql/',
  cache: new InMemoryCache()
});

Isso cria uma instância do Apollo Client usando o endpoint da API do SpaceX pelo qual faremos a query.

Com o nosso client, conseguimos finalmente fazer uma query. Adicione o seguinte código abaixo do client:

const { data } = await client.query({
  query: gql`
    query GetLaunches {
      launchesPast(limit: 10) {
        id
        mission_name
        launch_date_local
        launch_site {
          site_name_long
        }
        links {
          article_link
          video_link
          mission_patch
        }
        rocket {
          rocket_name
        }
      }
    }
  `
});

Isso faz algumas coisas:

• Cria uma query dentro das tag gql
• Cria uma query request usando client.query
• Usa await para garantir que ele finalize a requisição antes de continuar
• Por fim, desestrutura data dos resultados, que é onde as informações que precisamos estão armazenadas.

Dentro da query do GraphQL, estamos informando para a SpaceX que queremos pegar launchesPast, que são os últimos lançamentos da SpaceX, e que queremos os últimos 10 (limite). Dentro disso, definimos os dados que gostaríamos de recuperar.

Se adicionarmos um novo console log depois disso, podemos observar a aparência de data.

No entanto, uma vez que você recarregar a página, você notará que você não está vendo nada no console do navegador.

getStaticProps roda durante o processo de build, o que significa que ele roda no node. Portanto, podemos olhar o nosso terminal e veremos os logs:

Depois de ver isso, sabemos que o objeto data tem uma propriedade chamada launchesPast, que inclui um array de detalhes de lançamento.

Agora, podemos atualizar o retorno para usar launchesPast:

return {
  props: {
    launches: data.launchesPast
  }
}

Se adicionarmos nosso console.log de volta no topo da página para ver a aparência da prop launches, podemos observar que nossos dados de lançamento agora estão disponíveis como uma prop na nossa página:

Acompanhe com o commit!

Passo 4: Adicionado os dados de lançamento da SpaceX na página

Agora, vamos para a parte legal!

Temos nossos dados de lançamento, que conseguimos recuperar usando o Apollo Client, para solicitar do servidor do GraphQL da SpaceX. Fizemos uma requisição dentro de getStaticProps, de maneira que conseguimos deixar nossos dados disponíveis como a prop launches, que contém os dados de lançamento.

Navegando na página, vamos começar tirando proveito do que já existe. Por exemplo, podemos começar atualizando a tag h1 e o parágrafo abaixo dele para algo que descreva nossa página um pouco:

Depois, vamos utilizar os cards de link que já existem para incluir todos os nossos dados de lançamento.

Para fazer isso, vamos, primeiramente, adicionar um map dentro do grid da nossa página, onde o componente que retornamos é um dos cards, com os dados de lançamento preenchidos:

<div className={styles.grid}>
  {launches.map(launch => {
    return (
      <a key={launch.id} href={launch.links.video_link} className={styles.card}>
        <h3>{ launch.mission_name }</h3>
        <p><strong>Launch Date:</strong> { new Date(launch.launch_date_local).toLocaleDateString("en-US") }</p>
      </a>
    );
  })}

Podemos também nos livrar do resto dos cards padrão do Next.js, incluindo Documentation e Learn.

Nossa página, agora, inclui os últimos 10 lançamentos da SpaceX e a data do lançamento!

Podemos até mesmo clicar em qualquer um desses cards e, já que vinculamos o link para o vídeo, conseguimos agora ir diretamente para o vídeo ao clicar.

Acompanhe com o commit!

Próximos passos

A partir de agora, podemos incluir qualquer dado adicional de dentro do nosso array launches na nossa página. A API até mesmo inclui imagens de emblemas da missão, que podemos usar para mostrar imagens bonitas para cada lançamento.

Você também pode adicionar qualquer dado na query do GraphQL. Cada lançamento tem muitas informações disponíveis, incluindo a tripulação do lançamento e mais detalhes sobre o foguete.

https://api.spacex.land/graphql

• 🐦 Siga o autor no Twitter
• 📺 Inscreva-se no canal do autor no YouTube
• 📫 Assine a newsletter do autor
• 💝 Patrocine o autor