Forem: Juliana Macêdo

Como publicar um pacote no npm: um guia passo a passo

Juliana Macêdo — Wed, 13 Nov 2024 20:24:37 +0000

Publicar pacotes no NPM (Node package manager) não é apenas uma forma de compartilhar seu trabalho com outros desenvolvedores, mas também de se destacar na comunidade de desenvolvimento. Imagine criar uma solução reutilizável que possa ser integrada a diversos projetos pelo mundo todo, economizando tempo e esforço de outros programadores.

Neste artigo, você aprenderá, passo a passo, como configurar, publicar e manter seu próprio pacote no NPM, tornando suas contribuições acessíveis e aumentando sua visibilidade como desenvolvedor.

Pré-requisitos

Antes de começar, certifique-se de que tenha:

O NPM instalado. Você pode baixá-lo em nodejs.org ou utilizar o NVM (Node version manager).
Uma conta criada no npmjs.com

Execute os comandos abaixo no terminal para verificar que a instalação do Node.js e do NPM foram bem-sucedidas.

node -v
npm -v

Se a instalação estiver correta, o terminal exibirá a versão de cada.
O resultado será parecido com o abaixo:

$ v20.18.0 # node -v
$ 10.8.2 # npm -v

Configurando o projeto

Comece criando uma pasta com o nome que você deseja para o pacote. No meu caso escolhi "string-reverser-jm".

mkdir string-reverser-jm # cria a pasta via terminal
cd string-reverser-jm # acessa a pasta via terminal

Inicialize o NPM:

npm init

Ao executar o comando acima, o terminal fará algumas perguntas para criar o arquivo package.json.
Segue explicação de cada item que precisamos ter preenchido.

name: Um identificador exclusivo para o pacote.
version: Utilize versionamento semântico para indicar alterações.
description: Uma breve explicação sobre o que o pacote faz.
main: O arquivo do ponto de entrada, por exemplo, index.js.
keywords: Palavras-chave para categorizar e facilitar que outros desenvolvedores encontrem o pacote.
author: Adicione detalhes relevantes do autor.
license: A licença define como o código pode ser usado, modificado e distribuído por outros. A licença mais comum é a MIT, que é permissiva e permite grande liberdade de uso, desde que seja fornecido o aviso de direitos autorais original.

Caso termine as perguntas e o NPM tenha criado o arquivo sem alguma dessas informações, abra o arquivo criado em um editor e adicione o que estiver faltando.

Exemplo:

{
  "name": "string-reverser-jm",
  "version": "1.0.0",
  "description": "A simple utility to reverse strings, useful for demonstrations and small projects.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"No test specified\" && exit 1"
  },
  "author": "Juliana Macedo <contact@starcoders.info> (https://www.starcoders.info)",
  "keywords": [
    "string",
    "reverse",
    "utility"
  ],
  "license": "MIT"
}

Escrevendo o código

Crie o arquivo index.js na raiz do projeto.

function reverseString(str) {
  if (typeof str !== "string") {
    throw new TypeError("Expected a string as input");
  }
  return str.split("").reverse().join("");
}

module.exports = reverseString;

Testando o pacote

Para testar o pacote antes de publicá-lo, vamos utilizar o comando npm link

No diretório do pacote, execute o comando:

npm link

No projeto onde deseja testar o pacote, execute o comando:

npm link string-reverser-jm

Importe e use o pacote no seu projeto de teste para garantir que está funcionando:

const reverseString = require("string-reverser-jm");
console.log(reverseString("Hello, world!")); // Output: '!dlrow ,olleH'

Para remover os links criados, basta executar o comando npm unlink string-reverser-jm no diretório do projeto de teste e depois npm unlink no diretório do pacote.

Preparando o pacote para publicação

Primeiro, crie um repositório Git para o pacote e vincule-o ao NPM. Isso aumenta a transparência e confiança ao disponibilizar o código-fonte, facilita colaborações e contribuições da comunidade, e permite automação com CI/CD para um gerenciamento e manutenção mais eficientes.

Para vincular ao NPM, copie o endereço https do repositório e adicione-o ao package.json:

{
  "name": "string-reverser-jm",
  "version": "1.0.0",
  "description": "A simple utility to reverse strings, useful for demonstrations and small projects.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"No test specified\" && exit 1"
  },
  "author": "Juliana Macedo <contact@starcoders.info> (https://www.starcoders.info)",
  "keywords": [
    "string",
    "reverse",
    "utility"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/Jullymac/string-reverser-jm.git"
  }
}

.gitignore: Crie um arquivo .gitignore para excluir pastas e arquivos, como node_modules e .env, do versionamento.
.npmignore: Crie um arquivo .npmignore para especificar quais arquivos e pastas não devem ser incluídos no pacote NPM.
README.md: Crie um arquivo com informações sobre o pacote.

Publicando o pacote

Faça login no NPM usando seus dados de acesso:

npm login

Execute o comando abaixo para publicar o pacote:

npm publish

Pronto, em breve o pacote estará disponível no registro do NPM!
https://www.npmjs.com/package/string-reverser-jm

Atualizando o pacote

Ao fazer atualizações ou correções de bugs, aumente o número da versão no package.json de acordo com o versionamento semântico utilizando um dos comandos abaixo:

npm version patch   # Para correções
npm version minor   # Para novas funcionalidades que são compatíveis com versões anteriores
npm version major   # Para alterações significativas, que podem não ser compatíveis com versões anteriores

E depois, publique a versão atualizada:

npm publish

Problemas frequentes:

Package Name Already Taken: Se a publicação falhar porque já existe um pacote com o mesmo nome, escolha outro nome, um que ainda não tenha sido usado.
Authentication Errors: Certifique-se que está logado e tem todas as permissões necessárias para publicar.
Version Conflicts: Se tentar publicar sem atualizar o número da versão, o NPM rejeitará sua publicação. Use npm version para aumentar a versão.

Atomic Design in Frontend (english)

Juliana Macêdo — Sun, 27 Oct 2024 00:43:03 +0000

I have been working with web development since 2009, and over the years, I have witnessed a significant evolution in frameworks and development standards. One of the most significant changes was the rise of component-based development, which today stands out as one of the main approaches.

Component-based development is a software development approach where systems are built from independent parts, called components, which can be reused in different parts of a project or even across different projects. In the front-end, tools like React, Angular, and Vue.js heavily utilize this concept.

As we know, nothing is perfect, and this approach comes with some challenges, such as:

What is the ideal size for a component?
How should they be organized?
How can we preserve reusability?

Atomic Design helps us address these challenges.

What is Atomic Design?

Atomic Design is an interface design methodology proposed by Brad Frost, aiming to create more consistent and scalable design systems. It is based on the concept that an interface can be broken down into small, reusable parts.

In front-end development, Atomic Design is an approach to creating component systems in a modular and scalable way. The methodology allows for building the interface from reusable components, organized hierarchically from the simplest to the most complex, facilitating development, maintenance, and scalability of the project.

Atomic Design suggests dividing components into 5 stages:

1. Atoms: These are the simplest and most basic elements of the interface, which cannot be broken down into smaller parts. They are independent and usually have no behavior on their own. Atoms can be basic HTML tags or CSS variables, such as colors, fonts, spacing, and animations.

2. Molecules: These are combinations of atoms that work together to form a minimal functionality. Molecules have a more defined behavior and often represent small parts of the interface.

3. Organisms: These are groups of molecules and atoms that form more complex and distinct sections of the interface. An organism might represent a complete functional area of a page.

4. Templates: Templates are layouts composed of organisms, structurally organized to form the structure of a page. However, templates are still at the layout level, without specific data.

5. Pages: Pages are specific instances of templates, where real content and data are filled in. Pages represent the most concrete stage of Atomic Design, reflecting the final version the user will see.

For those who want to dive deeper, the full version of the article is available on Medium. There, I included practical examples, code snippets, and images to illustrate each concept in detail.

👉 Check out the full article on Medium

I hope this content is helpful for those looking to improve the organization and scalability of their frontend projects! If you have any questions or want to discuss the topic further, feel free to comment here or on Medium.

Atomic Design no Frontend (português)

Juliana Macêdo — Sun, 27 Oct 2024 00:37:58 +0000

Tenho trabalhado com desenvolvimento web desde 2009, e, nesses anos, testemunhei uma grande evolução nos frameworks e padrões de desenvolvimento. Uma das mudanças mais significativas foi o surgimento do desenvolvimento baseado em componentes (ou component-based development), que hoje se destaca como uma das principais abordagens.

Desenvolvimento baseado em componentes é uma abordagem de desenvolvimento de software em que os sistemas são construídos a partir de partes independentes, chamadas componentes, que podem ser reutilizados em diferentes partes de um projeto ou até em projetos distintos. No front-end, ferramentas como React, Angular e Vue.js utilizam fortemente esse conceito.

Como sabemos, nada é perfeito, e essa abordagem vem com alguns desafios. Entre eles estão:

Qual seria o tamanho ideal para um componente?
Como organizá-los?
Como preservar a reutilização?

O Atomic Design nos ajuda justamente com isso.

O que é Atomic Design?

Atomic Design é uma metodologia de design de interface proposta por Brad Frost que visa criar sistemas de design mais consistentes e escaláveis. Ela se baseia no conceito de que uma interface pode ser decomposta em pequenas partes reutilizáveis.

No front-end, o Atomic Design é uma abordagem para criar sistemas de componentes de forma modular e escalável. A metodologia permite que a interface seja construída a partir de componentes reutilizáveis, organizados de maneira hierárquica, do mais simples ao mais complexo, facilitando o desenvolvimento, a manutenção e a escalabilidade do projeto.

O Atomic Design sugere dividir os componentes em 5 níveis:

1. Átomos (Atoms): São os elementos mais simples e básicos da interface, que não podem ser decompostos em partes menores. Eles são independentes e geralmente não têm comportamento por conta própria. Podem ser tags HTML básicas ou variáveis de CSS, como cores, fontes, espaçamentos e animações.

2. Moléculas (Molecules): São combinações de átomos que trabalham juntos para formar uma funcionalidade mínima. Essas moléculas já têm um comportamento mais definido e geralmente representam pequenas partes da interface.

3. Organismos (Organisms): São agrupamentos de moléculas e átomos que formam seções mais complexas e distintas da interface. Um organismo pode representar uma área funcional completa de uma página.

4. Templates: São layouts compostos por organismos arranjados de maneira estrutural para formar a estrutura da página. No entanto, os templates ainda estão no nível de layout, sem dados específicos.

5. Páginas (Pages): São instâncias específicas dos templates, onde o conteúdo real e os dados são preenchidos. As páginas são o estágio mais concreto do Atomic Design, representando a versão final que o usuário verá.

Para quem quiser se aprofundar, a versão completa do artigo está disponível no Medium. Lá, incluí exemplos práticos, snippets de código, e imagens para ilustrar cada conceito em detalhe.

👉 Confira o artigo completo no Medium

Espero que este conteúdo seja útil para quem está buscando melhorar a organização e escalabilidade de seus projetos frontend! Se tiverem dúvidas ou quiserem discutir mais sobre o assunto, fiquem à vontade para comentar por aqui ou no Medium.

Como adicionar o Redux ao Next.js

Juliana Macêdo — Sat, 14 Nov 2020 21:23:09 +0000

Nesse post vou explicar o passo a passo para instalar o Redux no NextJs.
Usaremos a versão mais atual de ambos, que no momento é NextJs v10.0.1 e Redux 7.2.2.

Você pode ver o código completo no repositório abaixo:

Jullymac / post_nextjs-redux

Instalação

Iniciaremos instalando o NextJs com o create app:

npx create-next-app project

Este comando criará um projeto no diretório "project" com a estrutura inicial para trabalharmos no NextJs.

O próximo passo é instalar o Redux para ReactJs e mais algumas depedências:

npm install redux react-redux next-redux-wrapper
npm install --save-dev redux-devtools-extension

redux = Redux package
react-redux = Extensão para utilizar o Redux com ReactJs
next-redux-wrapper = HOC que une Next.js e Redux
redux-devtools-extension = Pacote para debugar alterações de estado

Agora que temos tudo instalado, é hora de colocar a mão na massa!

Actions (ações)

Uma ação é um objeto JavaScript simples que possui um campo de tipo.
Você pode pensar em uma ação como um evento que descreve algo que aconteceu na aplicação.

Primeiro vamos criar nossa lista de tipos de ações em /store/actions/index.js:

// *** USER ***
export const USER_UPDATE = "USER_UPDATE";
export const USER_RESET = "USER_RESET";

// *** SETTINGS ***
export const USER_SETTINGS_UPDATE_LANGUAGE = "USER_SETTINGS_UPDATE_LANGUAGE";

// *** POSTS ***
export const POSTS_UPDATE_LIST = "POSTS_UPDATE_LIST";

Agora vamos criar as nossas ações.

As de usuário em /store/actions/users/index.js:

import { USER_UPDATE, USER_RESET } from "../";

export const userUpdate = (user) => ({
  type: USER_UPDATE,
  payload: user,
});

export const userReset = () => {
  return {
    type: USER_RESET,
  };
};

As de configurações de usuário, em /store/actions/users/settings.js:

import { USER_SETTINGS_UPDATE_LANGUAGE } from "../";

export const settingsUpdateLang = (lang) => ({
  type: USER_SETTINGS_UPDATE_LANGUAGE,
  payload: lang,
});

As de postagens, em /store/actions/posts/index.js:

import { POSTS_UPDATE_LIST, POSTS_GET_LIST } from "../";

export const postsUpdateList = (posts) => {
  return {
    type: POSTS_UPDATE_LIST,
    payload: posts,
  };
};

Reducers

O próximo passo é criar os reducers.

Um reducer é uma função que recebe o estado atual e um objeto de ação, decide como atualizar o estado se necessário e retorna o novo estado.

O novo estado retornado é o que será guardado na store.

Vamos criar o reducer de usuário em /store/reducers/users/index.js:

import { HYDRATE } from "next-redux-wrapper";
import { USER_UPDATE, USER_RESET } from "../../actions";

const initialState = {
  id: null,
  firstName: null,
  lastName: null,
  fullName: null,
  avatar: null,
};

const reducer = (state = initialState, action) => {
  switch (action.type) {
    case HYDRATE:
      return { ...state, ...action.payload.user };
    case USER_UPDATE:
      const newState = { ...state, ...action.payload };
      newState.fullName = `${newState.firstName} ${newState.lastName}`;
      return newState;
    case USER_RESET:
      return initialState;
    default:
      return state;
  }
};

export default reducer;

O reducer de configurações do usuário em /store/reducers/users/settings.js:

import { HYDRATE } from "next-redux-wrapper";
import { USER_SETTINGS_UPDATE_LANGUAGE } from "../../actions";

const initialState = {
  language: "pt-br",
  postsPerPage: 4,
};

const reducer = (state = initialState, action) => {
  switch (action.type) {
    case HYDRATE:
      return { ...state, ...action.payload.settings };
    case USER_SETTINGS_UPDATE_LANGUAGE:
      return { ...state, language: action.payload };
    default:
      return state;
  }
};

export default reducer;

O reducer de postagens em /store/reducers/posts/index.js:

import { HYDRATE } from "next-redux-wrapper";
import { POSTS_UPDATE_LIST } from "../../actions";

const initialState = [];

const reducer = (state = initialState, action) => {
  switch (action.type) {
    case HYDRATE:
      return action.payload.posts;
    case POSTS_UPDATE_LIST:
      return action.payload;
    default:
      return state;
  }
};

export default reducer;

Como deve ter notado, nossos reducers possuem um tipo de ação chamado "HYDRATE" que importamos do pacote next-redux-wrapper.

O termo "Hydrate" é bastante usado quando falamos de server-side rendering (SSR). Hydrate consiste em fazer a aplicação ajustar a versão que vem do server com a versão do client.
Mas ao invés de substituir tudo, nós apenas atualizamos o conteúdo do server aplicando as alterações do client ao conteúdo existente.

O NextJs já faz um trabalho excepcional com o Hydrate do DOM. Para nossa Redux store, nós precisamos adicionar o tipo de ação "HYDRATE" e informar como queremos que essa atualização ocorra.

No paylod do "HYDRATE" recebemos todo o estado da store. Nos nossos exemplos fazemos uma substituição apenas dos dados do reducer que está sendo hidratado no momento.
Em uma aplicação real, cada caso deve ser analisado para ser feita a reconciliação da forma correta.

Com todos os reducers criados, vamos combiná-los para adicionar na nossa store.
Em /store/reducers/index.js:

import { combineReducers } from "redux";
import settingsReducer from "./user/settings";
import userReducer from "./user";
import postsReducer from "./posts";

export default combineReducers({
  settings: settingsReducer,
  user: userReducer,
  posts: postsReducer,
});

Store

O estado atual da aplicação é guardado em um objeto chamado store.

Vamos criar a store em /store/index.js:

import { createStore } from "redux";
import { createWrapper } from "next-redux-wrapper";
import { composeWithDevTools } from "redux-devtools-extension/developmentOnly";
import reducers from "./reducers";

const makeStore = () => {
  // Create store
  const store = createStore(reducers, composeWithDevTools());

  // Return store
  return store;
};

// export an assembled wrapper
export const storeWrapper = createWrapper(makeStore, { debug: false });

Inicializar a store

Tudo criado, mas nada disso funciona se não fizermos a inicialização da store na aplicação, certo?

Vamos alterar o arquivo /pages/_app.js. Nele vamos importar o wrapper da nossa store e vamos aplicá-la no export da aplicação. O resultado:

import "../styles/globals.css";
import { storeWrapper } from "../store";

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

export default storeWrapper.withRedux(MyApp);

Mais algumas terminologias

Dispatch

A store do Redux possui um método chamado dispatch. A única forma que temos de atualizar um estado é chamando o dispatch passando uma ação. A store vai executar o reducer e salvar o novo estado.

Usamos o dispatch sempre que precisamos atualizar algo na store.

Selectors

Selectors são funções que sabem como extrair informações específicas do estado da store.

Usamos os selectores para recuperar um valor guardado na store.

Obs: Alternativamente também podemos acessar todo o estado utilizando o método getState disponível na store do Redux.

Exemplos de utilização

Existem algumas formas de acessar nossa store, que variam de acordo com o local que tentamos acessar.

Em componentes usamos Hooks

Dentro de componentes conseguimos manipular a store utilizando hooks.
Para isso devemos fazer o import dos hooks:

import { useSelector, useDispatch } from "react-redux";

O useSelector Hook recebe uma função que tem acesso a todo o estado da store, e deve retornar apenas as informações que desejamos utilizar.

Exemplo:

const { language } = useSelector((state) => state.settings);
const { id, fullName } = useSelector((state) => state.user);
const posts = useSelector((state) => state.posts);

O useDispatch Hook não recebe parâmetros, e sempre retorna a função de dispatch.

const dispatch = useDispatch();

Para fazermos o dispatch, devemos importar a ação que vamos utilizar e enviá-la para o dispatch:

import { settingsUpdateLang } from "../store/actions/user/settings";

const handleSwitchLang = () => {
  const newLang = language === "pt-br" ? "en" : "pt-br";
  dispatch(settingsUpdateLang(newLang));
};

Em getServerSideProps e getStaticProps usamos o context

Para isso, devemos importar o nosso storeWrapper e utilizarmos o método específico de cada um.

import { storeWrapper } from "./../store";

Em getServerSideProps :

export const getServerSideProps = storeWrapper.getServerSideProps(
  async ({ store }) => {
    const res = await fetch("https://jsonplaceholder.typicode.com/posts");
    const posts = await res.json();

    // Example get store state
    const state = store.getState();
    const { postsPerPage } = state.settings;

    //Example dispatch
    store.dispatch(postsUpdateList(posts.slice(0, postsPerPage)));

    return {
      props: {},
    };
  }
);

Nos exemplos acima podemos ver como recuperar o estado, nesse caso utilizando o store.getState(); e como fazer o dispatch, utilizando store.dispatch.

Podemos utilizar exatamente da mesma forma no getStaticProps, apenas alteramos o método do storeWrapper:

export const getStaticProps = storeWrapper.getStaticProps(async ({ store }) => {
  // ...

  return {
    props: {},
  };
});