DEV Community: Caio Fuzatto

Iniciando um backoffice rapidamente com AdminJS

Caio Fuzatto — Thu, 16 Nov 2023 16:54:20 +0000

Na vida de um dev é praticamente obrigatório ter passado por uma task em que você precisava criar um backoffice para um sistema. Seja para um cliente ou para a própria empresa, é muito comum que seja necessário criar um painel de administração para gerenciar os dados do sistema. Hoje nós vamos configurar do 0 uma aplicação com o AdminJS, uma ferramenta que cria o backoffice para você.

Esse post é um tutorial step-by-step do AdminJS. Se você tem interesse em conhecer mais a ferramenta antes de iniciar, sugiro ler o artigo AdminJS: diga adeus a templates de backoffice.

Iniciando o projeto

Primeiro de tudo precisamos criar uma pasta (mkdir setup-admins) e iniciar o projeto node (yarn init). Após isso vamos instalar o AdminJS (yarn add adminjs) e o Typescript. Você pode copiar o comando abaixo e fazer tudo isso de uma vez só:

mkdir setup-admins && cd setup-admins && yarn init -y && yarn add adminjs typescript && yarn add -D ts-node tslib

Além disso também vou instalar o Typescript, e criar o arquivo tsconfig.json com o seguinte comando:

{
  "compilerOptions": {
    "target": "ESNEXT",
    "module": "NodeNext",
    "moduleResolution": "nodenext",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

Também será necessário adicionar o seguinte código no package.json:

{
  "type": "module",
  "scripts": {
    "start": "ts-node-esm app.ts"
  }
}

O AdminJS suporte apenas ECMAScript modules, por isso precisamos adicionar o type: module no package.json e o ts-node-esm no scripts.

Configurando o AdminJS

Agora você vai precisar escolher entre os diversos plugins e adapters que o AdminJS suporta. Essa decisão é importante para definir o framework http e o banco de dados que você vai utilizar na aplicação.

Eu vou de Express e MongoDb/Mongoose.

Configurando o framework HTTP (Express)

yarn add @adminjs/express express tslib express-formidable @types/express && yarn add -D @types/express

Agora vamos criar o arquivo app.ts na raiz do projeto e colar o seguinte código:

import AdminJS from 'adminjs'
import AdminJSExpress from '@adminjs/express'
import express from 'express'

const PORT = 3000

const start = async () => {
  const app = express()

  const admin = new AdminJS({})

  const adminRouter = AdminJSExpress.buildRouter(admin)
  app.use(admin.options.rootPath, adminRouter)

  app.listen(PORT, () => {
    console.log(`AdminJS iniciado em http://localhost:${PORT}${admin.options.rootPath}`)
  })
}

start()

Configuração do banco de dados (Mongoose)

Vamos começar a configurar o banco de dados, para isso vamos utilizar o Mongoose. Primeiro vamos instalar as dependências:

yarn add mongoose @adminjs/moongose

Vamos começar a configuração registrando o adapter do Mongoose no AdminJS. Para isso vamos adicionar o seguinte código no topo arquivo app.ts:

// outros imports [..]
import * as AdminJSMongoose from '@adminjs/mongoose'

AdminJS.registerAdapter({
  Resource: AdminJSMongoose.Resource,
  Database: AdminJSMongoose.Database,
})
// resto do código [...]

E dentro da função start vamos iniciar a conexão com o banco de dados:

const start = async () => {
  const app = express()
  // adicione a linha abaixo no código
  await mongoose.connect("<mongo db url>");

  const admin = new AdminJS({})
  // resto do código [...]
}

Lembre-se de alterar trecho <mongo db url> para a url do seu banco de dados. Se você não tiver um MongoDB configurado, você pode criar um gratuitamente no MongoDB Atlas.

Criando o primeiro CRUD

Agora que já temos o AdminJS configurado, vamos criar o primeiro CRUD. Para o tutorial vamos levar em consideração que estamos fazendo um backoffice para uma locadora de filmes. Para isso vamos criar um arquivo movie.entity.ts com a seguinte estrutura:

export interface Actor {
  name: string;
  surname: string;
}

export interface Movie {
  title: string;
  synopsis: string;
  date: Date;
  price: number;
  categories: string[];
  actors: Actor[];
}

Observe que adicionei vários tipos diferentes de dados para mostrar como o AdminJS trata cada um deles.

Além da interface também vamos criar o schema do Mongoose, onde vamos mapear todas as propriedades do nosso modelo para o banco de dados. Para isso vamos criar o arquivo movie.schema.ts com o seguinte código:

import { Schema, model } from "mongoose";
import { Actor, Movie } from "./movie.entity.js";

export const ActorSchema = new Schema<Actor>({
  name: { type: String, required: true },
  surname: { type: String, required: true },
})

export const MovieSchema = new Schema<Movie>(
  {
    title: { type: String, required: true },
    synopsis: { type: String, required: true },
    date: { type: Date, required: true },
    price: { type: Number, required: true },
    categories: { type: [String], required: true },
    actors: { type: [ActorSchema], required: true },
  },
  { timestamps: true },
)

export const MovieModel = model<Movie>('Movie', MovieSchema);

Por fim, precisamos registrar o nosso modelo no AdminJS, que fornece a interface ResourceWithOptions, que tem as opções que podemos passar para cada resource. Então vamos criar o arquivo movie.resource.ts com o seguinte código:

import { ResourceWithOptions } from "adminjs";
import { MovieModel } from "./movie.schema.js";

export const MovieResource: ResourceWithOptions = {
  resource: MovieModel,
  options: {
    navigation: {
      icon: "Film",
    },
    properties: {
      synopsis: { type: "richtext" },
    },
  },
};

Para deixar o formulário mais adequado, configurei um ícone para o menu de navegação e o tipo do campo synopsis para richtext. Você pode ver mais sobre customização de propriedades ou acessar a lista de ícones FatherIcons.

Agora só precisamos de passar nosso recurso na opções do AdminJS, então vamos adicionar o seguinte código no o arquivo app.ts:

// outros imports [...]
import AdminJS, { AdminJSOptions } from "adminjs";
import { MovieResource } from "./movie.resource.js";

//[...]
const start = async () => {
  //[...]  
  const adminOptions: AdminJSOptions = {
    resources: [MovieResource],
  }
  const admin = new AdminJS(adminOptions);
  //[...]
};

Agora podemos acessar http://localhost:3000/admin/resources/Movie/actions/new e ver o formulário do CRUD de filmes:

Dashboard

O AdminJS vem com um dashboard padrão que é bem voltado para o desenvolvedor. Mas como tudo no AdminJS, ele também pode ser customizado. Então vamos criar um dash bem simples mostrando a quantidade de livros cadastrados. O AdminJS utiliza o styled-components e a lib já vem instalada com o pacote @adminjs/design-system. Então vamos instalar o pacote de tipagem do styled-components:

yarn add -D @types/styled-components

Agora vamos criar o arquivo dashboard.component.tsx que será o componente React do dashboard, com o seguinte código:

import { ApiClient } from "adminjs";
import React, { useEffect, useState } from "react";
import styled from "styled-components";

type DashboardResponse = {
  moviesCount: number;
}

export const Dashboard = () => {
  const [data, setData] = useState<DashboardResponse>({ moviesCount: 0 });
  const api = new ApiClient();

  useEffect(() => {
    getData();
  }, []);

  const getData = async () => {
    const response = await api.getDashboard<DashboardResponse>();
    setData(response.data);
  };

  const Box = styled.div`
    background-color: #fff;
    border-radius: 4px;
    padding: 20px;
    margin: 20px;
    box-shadow: 0 0 4px rgba(0, 0, 0, 0.1);
    border-color: #ddd;
    max-width: 200px;
  `

  return (
    <div>
      <h1>Dashboard</h1>
      <Box>
        <h2>Filmes</h2>
        <span>{data.moviesCount}</span>
      </Box>
    </div>
  );
};

export default Dashboard;

O ApiClient é uma classe utilitária do AdminJS que facilita a comunicação com o backend.

Para o AdminJS reconhecer o componente, precisamos carregar ele utilizando o ComponentLoader, onde vamos poder centralizar os nossos componentes customizados. Crie o arquivo components.ts com o seguinte código:

import { ComponentLoader } from "adminjs";

export const componentLoader = new ComponentLoader();

export const Components = {
  Dashboard: componentLoader.add("Dashboard", "./Dashboard.component"),
};

Hora de trabalhar na função que vai trazer os dados para o frontend do Dashboard, então crie um arquivo chamado dashboard.config.ts com o seguinte código:

import { AdminJSOptions } from "adminjs";
import { Components } from "./components.js";
import { MovieModel } from "./movie.schema.js";

const dashboardHandler = async () => {
  const moviesCount = await MovieModel.countDocuments();
  return { moviesCount };
};

export const DashboardOptions: AdminJSOptions["dashboard"] = {
  component: Components.Dashboard,
  handler: dashboardHandler,
};

A função dashboardHandler é responsável por trazer os dados que serão utilizados no frontend do Dashboard.

Agora só precisamos adicionar o DashboardOptions e o componentLoader nas opções do AdminJS, então vamos adicionar o seguinte código no arquivo app.ts:

import { componentLoader } from "./components.js";
import { DashboardOptions } from "./dashboard.config.js";

const adminOptions: AdminJSOptions = {
  resources: [MovieResource],
  dashboard: DashboardOptions, // adicione essa configuração
  componentLoader, // adicione essa configuração
};

Agora podemos acessar http://localhost:3000/admin e ver o nosso dashboard:

Aqui tivemos uma pequena amostra do que podemos fazer com customização de componentes no AdminJS. Você pode ver mais sobre esse assunto na documentação do AdminJS.

Autenticação

Como todo backoffice que se prese, precisamos de autenticar os usuários que acessam o sistema. Então agora vamos configurar a autenticação no AdminJS. Vamos precisar adicionar as libs para gerenciar sessão e criptografar as senhas:

  yarn add @adminjs/passwords bcrypt connect-mongo express-session  && yarn add -D @types/express-session @types/express

Agora vamos criar os arquivos entity, schema e resource para o Administrador. Crie o arquivo admin.entity.ts com o seguinte código:

export interface Admin {
  name: string;
  email: string;
  hashedPassword: string;
}

Vamos utilizar o hashedPassword para armazenar a senha criptografada do usuário. Agora vamos criar o arquivo admin.schema.ts com o seguinte código:

import { model, Schema } from "mongoose";
import { Admin } from "./admin.entity.js";

export const AdminSchema = new Schema<Admin>(
  {
    name: { type: String, required: true },
    email: { type: String, required: true, unique: true },
    hashedPassword: { type: String, required: true },
  },
  { timestamps: true }
);

export const AdminModel = model<Admin>("Admin", AdminSchema);

Por fim, vamos criar o arquivo admin.resource.ts com o seguinte código:

import passwordsFeature from "@adminjs/passwords";
import bcrypt from 'bcrypt';
import { AdminModel } from "./admin.schema.js";
import { componentLoader } from "./components.js";

const encryptPassword = async (password: string) => {
  const passwordHashed = await bcrypt.hash(password, 10);
  return passwordHashed;
};

export const AdminResource = {
  resource: AdminModel,
  options: {
    navigation: {
      icon: "User",
    },
    properties: { hashedPassword: { isVisible: false } },
  },
  features: [
    passwordsFeature({
      properties: {
        encryptedPassword: "hashedPassword",
        password: "password",
      },
      hash: encryptPassword,
      componentLoader: componentLoader,
    }),
  ],
};

Observe que estamos utilizando o bcrypt para criptografar a senha do usuário. Além disso estamos utilizando a funcionalidade de senha do AdminJS, disponibilizada no pacote @adminjs/passwords, que faz as trativas de exibição do campo senha e faz a criptografia da senha antes de salvar no banco de dados.

Agora vamos precisar acessar o CRUD de Admin para cadastrar o primeiro usuário antes de finalizar a configuração de autenticação. Então acesse http://localhost:3000/admin/resources/Admin/actions/new e crie o primeiro usuário.

Agora vamos configurar a autenticação no AdminJS. Para isso vamos criar o arquivo auth.config.ts com o seguinte código:

import MongoStore from "connect-mongo";
import { AdminModel } from "./admin.schema.js";
import bcrypt from "bcrypt";

const authenticate = async (email: string, password: string) => {
  const admin = await AdminModel.findOne({ email });
  if (!admin) return null;
  const isValidPassword = await bcrypt.compare(password, admin.hashedPassword);
  if (!isValidPassword) return null;
  return admin;
};

export const AuthOptions = {
  auth: {
    authenticate: authenticate,
    cookieName: "adminjs",
    cookiePassword: "sessionsecret",
  },
  session: (sessionStore: MongoStore) => ({
    store: sessionStore,
    resave: true,
    saveUninitialized: true,
    secret: "sessionsecret",
    cookie: {
      httpOnly: process.env.NODE_ENV === "production",
      secure: process.env.NODE_ENV === "production",
    },
    name: "adminjs",
  }),
};

A função authenticate é responsável por validar o usuário e senha informados na tela de login e retornar um usuário válido em caso de sucesso. Se você precisar fazer uma lógica diferenciada de autenticação, utilizando um provedor externo da empresa por exemplo, é aqui que você deve alterar.

Agora vamos adicionar o AuthOptions nas opções do AdminJS, então vamos adicionar o seguinte código no arquivo app.ts:

import MongoStore from "connect-mongo";

// [...]

const start = async () => {
  await mongoose.connect(process.env.MONGO_DB_URL || "");
  // as alterações começam aqui
  const sessionStore = MongoStore.create({
    client: mongoose.connection.getClient(),
    collectionName: "sessions",
    stringify: false,
    autoRemove: "interval",
    autoRemoveInterval: 1,
  });
  const adminOptions: AdminJSOptions = {
    resources: [MovieResource, AdminResource],
    dashboard: DashboardOptions,
    componentLoader,
  };
  const admin = new AdminJS(adminOptions);
  const adminRouter = AdminJSExpress.buildAuthenticatedRouter(
    admin,
    AuthOptions.auth,
    null,
    AuthOptions.session(sessionStore)
  );
  // e finalizam aqui 
  // [...]
};

Agora podemos acessar http://localhost:3000/admin e você será redirecionado para a tela de login do AdminJS:

Conclusão

Projeto completo no Github

Vimos como configurar o AdminJS, criar um CRUD, customizar o dashboard e configurar a autenticação. O AdminJS é uma ferramenta muito poderosa e que pode ser utilizada para criar backoffices rapidamente e se você tiver interesse em aprender mais sobre a ferramenta você pode ler o artigo AdminJS: diga adeus a templates de backoffice.

EcmaScript Modules na prática

Caio Fuzatto — Thu, 09 Nov 2023 13:27:24 +0000

Fala turma, para reforçar os conhecimentos que tive estudando EcmaScript modules, resolvi fazer um pequeno monorepo para praticar. Vamos conseguir ver na prática como funciona o suporte do NodeJS e dos browsers para o ESM, incluindo utilizar o ESM com o CommonJS, e também como utilizar o ESM com o TypeScript.

Exemplo 1: "type": "module"

Vamos começar com o exemplo mais utilizado. Eu criei uma pasta chamada esm-node-type-module para esse primeiro exemplo, dentro dela vamos criar um arquivo package.json com o seguinte conteúdo:

{
  "name": "esm-node-type-module",
  "version": "1.0.0",
  "description": "Exemplo de uso do ESM com o type module",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "author": "Caio Fuzatto",
  "license": "MIT"
}

Depois vamos criar os arquivos index.js e module1.js com o seguinte conteúdo:

// index.js
import { test1 } from './module1.js';

test1();

Uma das primeiras coisas que vamos notar é a extensão do arquivo deve ser especificada no import, diferente do "ESM transpilado" que conseguia inferir a extensão do arquivo. Expliquei tudo sobre isso no post Entendendo EcmaScript Modules.

// module1.js
export const test1 = () => {
  console.log('Estamos dentro de um módulo ESM');
}

Agora vamos rodar o comando yarn start e ver o resultado:

Opa, erro ao carregar o módulo. Mas felizmente o NodeJS nos dá duas dicas do que fazer, nesse primeiro exemplo vamos utilizar a primeira dica e adicionar "type": "module" no nosso package.json. Agora é só rodar novamente e ver o resultado:

$ node index.js
Estamos dentro de um módulo ESM

Compatibilidade com o CommonJS

O NodeJS também trouxe um suporte aos módulos ESM com o CommonJS, ou seja, podemos utilizar o ESM com o CommonJS. Para isso vamos criar um arquivo module2.cjs com o seguinte conteúdo:

const test2 = async () => {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  console.log("Estamos dentro de um módulo CommonJS");
};

module.exports = { test2 };

Observe que a extensão do arquivo é .cjs, isso é necessário para o NodeJS entender que esse arquivo é um módulo CommonJS.

E agora vamos importar esse módulo no nosso index.js:

import { test1 } from './module1.js';
import { test2 } from './module2.cjs';

test1();
await test2();

Fiz uma função async para você ver que o ESM suporta o uso de await no top-level de módulos. Incrível né?

Agora vamos rodar o comando yarn start e ver o resultado, que após 2 segundos será o seguinte:

$ node index.js
Estamos dentro de um módulo ESM
Estamos dentro de um módulo CommonJS

Exemplo 2: Extensão .mjs

Vamos agora para o segundo exemplo, que é o uso da extensão .mjs. Como já estamos familiarizados, vamos direto agora em?

Para isso vamos criar uma pasta chamada esm-node-mjs e dentro dela vamos criar um arquivo package.json com o seguinte conteúdo:

{
  "name": "esm-node-mjs",
  "version": "1.0.0",
  "description": "Exemplo de uso do ESM com a extensão .mjs",
  "main": "index.mjs",
  "scripts": {
    "start": "node index.mjs"
  },
  "author": "Caio Fuzatto",
  "license": "MIT"
}

Observe que nesse exemplo já estamos utilizando a extensão .mjs na propriedade main e no script start.

Agora vamos copiar os arquivos index.js e module1.js do exemplo anterior e renomear para index.mjs e module1.mjs respectivamente. Já o module2.cjs vamos renomear para module2.js. Além disso é importante ajustar os imports na index né? Confira como ficou:

import { test1 } from './module1.mjs';
import { test2 } from './module2.js';

test1();
await test2();

Percebeu que inverteu o jogo? Agora os módulos ESM precisam ter a extensão .mjs e os CommonJS utilizam a .js, enquanto no outro exemplo era o contrário. Agora vamos rodar o comando yarn start e temos o mesmo resultado:

$ node index.mjs
Estamos dentro de um módulo ESM
Estamos dentro de um módulo CommonJS

Exemplo 3: ESM no frontend

Vamos agora para o terceiro exemplo, que é o uso do ESM no frontend. Para isso vamos criar uma pasta chamada esm-frontend e dentro dela vamos criar um arquivo app.js com o seguinte conteúdo:

import { test1 } from './module1.js';

document.getElementById('content').textContent = await test1();

Bem semelhante aos exemplos de NodeJS, a diferença aqui é que estamos utilizando o document para alterar o conteúdo de um elemento HTML.

Agora vamos criar nosso módulo, para isso vamos criar um arquivo module1.js com o seguinte conteúdo:

export const test1 = async () => {
  console.log("Estamos dentro de um módulo ESM | ", new Date().toISOString());
  await new Promise((resolve) => setTimeout(resolve, 2000));
  console.log("Conteúdo carregou | ", new Date().toISOString());
  return "Fui gerado por um módulo ESM";
};

E por fim, a página HTML que vai carregar o nosso módulo. Para isso vamos criar um arquivo index.html com o seguinte conteúdo:

<!DOCTYPE html>
<head>
  <title>ESM no Frontend</title>
</head>
<body>
  <div id="content">Carregando...</div>
  <script type="module" src="app.js"></script>
</body>

Observe que estamos utilizando o atributo type="module" para indicar que o arquivo app.js é um módulo ESM.

Para testar (e não tomar erro de CORS) vou utilizar a lib HTTP-SERVE. Você pode rodar npx http-serve dentro da pasta esm-frontend e acessar a URL http://localhost:8080 para ver o resultado:

Exemplo 4: ESM nativo e Typescript

Vamos agora para o quarto exemplo, que é o uso do ESM nativo com o TypeScript. Para isso vamos criar uma pasta chamada esm-typescript e dentro dela vamos criar um arquivo package.json com o seguinte conteúdo:

{
  "name": "esm-node-type-module",
  "version": "1.0.0",
  "description": "Exemplo de uso do ESM com o type module",
  "main": "index.js",
  "license": "MIT",
  "author": "Caio Fuzatto",
  "scripts": {
    "start": "ts-node-esm index.ts"
  },
  "type": "module",
  "devDependencies": {
    "ts-node": "^10.9.1",
    "typescript": "^5.2.2"
  }
}

Observe que estamos utilizando o ts-node-esm para rodar o TypeScript com o ESM nativo. Você pode ver mais sobre no Github do ts-node

Agora vamos criar nosso arquivo module1.ts com o seguinte conteúdo:

export const test1 = async () => {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  console.log("Estamos dentro de um módulo ESM nativo no Typescript");
};

Até aqui tudo ok né? Agora vamos criar o index.ts com o seguinte conteúdo:

import { test1 } from './module1.js';

await test1();

Observe que estamos importando o módulo module1.js e não module1.ts. Isto é porque o TypeScript é transpilado para JavaScript, e o Node.js vai executar o código JavaScript transpilado, não o código TypeScript original.

Agora vamos rodar o comando yarn start e ver o resultado:

$ ts-node-esm index.ts
Estamos dentro de um módulo ESM nativo no Typescript

Conclusão

Bom pessoal, espero que tenham gostado do conteúdo. Conseguimos ver várias formas de utilizar o ESM nativo do NodeJS e dos browsers, e também como utilizar o ESM com o CommonJS. Vale sempre a pena avaliar a situação do projeto para escolher qual desses caminhos seguir, se precisar de ajuda da uma olhada no meu post Entendendo o EcmaScript Modules. Você pode ver o código completo no Github. Até a próxima!

Alterando uma lib Node de forma rápida

Caio Fuzatto — Thu, 19 Oct 2023 17:53:22 +0000

Você já se deparou com um bug chato na lib que você instalou para resolver os seus problemas? Aquele bug que depois de procurar bastante você caiu numa issue do github onde descobriu que era um defeito na lib? Ou seu PO te pediu algo que a lib não faz e você não quer esperar o pull request ser aceito pra poder continuar o desenvolvimento?

A ideia hoje é aprender como fazer um patch de uma alteração sua em uma lib, e também aprender a buildar sua lib corretamente com suas alterações, bora la?

Lib patch-package

Durante muito tempo o patch-package foi a solução mais utilizada para resolver esse problema. Ele é um pacote que permite que você faça alterações em libs que você instalou via npm, e que essas alterações sejam aplicadas toda vez que alguém rodar o comando npm install no seu projeto.

Para começar a usar o patch-package, você precisa instalar ele no seu projeto:

yarn add patch-package postinstall-postinstall

E adicionar um script no seu package.json:

"scripts": {
  "postinstall": "patch-package"
}

O postinstall-postinstall é um pacote que vai executar o comando patch-package toda vez que alguém rodar o comando npm install no seu projeto.

Agora você pode fazer as alterações que você quiser na lib e depois é só rodar o comando yarn patch-package <nome da lib> que o patch-package vai criar um arquivo .patch com as alterações que você fez.

Além disso, uma das vantagens que eu gosto muito do patch-package é o a flag --create-issue que abre uma página com uma issue em draft no github da lib que você está alterando. Assim você pode abrir uma issue com a sua alteração e quem sabe ela não é aceita e você não precisa mais fazer o patch?

Se quiser saber mais sobre contribuições em projetos open-source da uma olhada la no último artigo sobre A cultura open-source.

Yarn V2

O Yarn V2 também trás uma solução nativa para resolver esse problema, o patch. Com ele você consegue fazer a mesma coisa que o patch-package, mas de forma nativa. Bora vê como funciona!

Provavelmente você ainda não deve estar utilizando o Yarn V2 em nenhum dos seus projetos, então comece configurando a nova versão:

yarn set version berry && yarn install

Isso vai instalar a V2 e vai adicionar o arquivo .yarnrc.yml na raiz do seu projeto, além da pasta .yarn que vai conter os arquivos de cache do Yarn.

Para começar digite o comando patch e o nome da lib que você quer alterar, no meu caso será a @adminjs/passwords:

yarn patch @adminjs/passwords

Você verá um output parecido com esse:

Olha que legal, o yarn criou uma pasta que contém todos os arquivos da lib, e você pode fazer as alterações necessárias para resolver o seu problema. Para o tutorial eu vou só adicionar um console.log("teste") só para gente ver o resultado.

Terminou as alterações? Hora de "salvar" as alterações e aplicar o patch:

yarn patch-commit -s <caminho da pasta gerada pelo yarn>

Com esse comando o yarn vai criar um arquivo .yarn/patches/<nome da lib>.patch com as alterações que você fez. Olha como ficou o meu:

diff --git a/src/bundle-component.ts b/src/bundle-component.ts
index 28a36f32426f984f7aac103a3a45775671ab7891..d5d727e2b4059b2e4d2aa24be650a8bef374b306 100644
--- a/src/bundle-component.ts
+++ b/src/bundle-component.ts
@@ -12,6 +12,7 @@ const bundleComponent = (
   componentName: string,
 ) => {
   const componentPath = path.join(__dirname, `./components/${componentName}`)
+  console.log("teste")
   return loader.add(componentName, componentPath)
 }

Agora é só commitar esse arquivo e pronto, toda vez que alguem rodar yarn install no seu projeto as alterações serão aplicadas na LIB.

pnpm

Se você navegou na net pelos últimos dias, você deve conhecer o pnpm, um gerenciador de pacotes que promete ser mais rápido que o Yarn e o NPM. Ele também tem uma solução nativa para resolver esse problema, o patch.

Assim como no Yarn aqui também temos o comando pnpm patch <nome da lib> que vai criar uma pasta com os arquivos da lib para você alterar.

Também podemos aproveitar a própria node_modules para fazer nossas mudanças, sem precisar criar uma pasta nova e além disso conseguindo testar a alteração diretamente no seu projeto. É só especificar a pasta no comando o patch-commit, como no exemplo abaixo:

pnpm patch-commit node_modules/@adminjs/passwords

Buildando a Lib

A gente adicionou o console.log("teste") na pasta src do projeto mas o log não está sendo exibido quando você roda o projeto. Isso acontece porque o arquivo src não é o que está sendo executado, e sim o dist ou build. Então vamos buildar a lib para que as alterações sejam aplicadas.

No seu terminal caminhe até a pasta da lib na node modules. No meu caso o comando ficou assim:

cd node_modules/@adminjs/passwords

Agora precisamos instalar as dependências da lib na pasta dela, para isso vamos usar o comando pnpm install e depois disso basta rodar o comando pnpm build para buildar a lib.

pnpm install && pnpm build

Agora quando você rodar o projeto você vai ver a alteração acontecendo.

Agora você pode usar os comandos de patch apontando para a pasta da lib na node_modules e a alteração ficará salva. Veja o novo arquivo de patch com o console.log em dois arquivos diferentes:

diff --git a/build/bundle-component.js b/build/bundle-component.js
index 9ac9a32d7a3f412fd0e8a90441fd0c35ec694e0e..f7e4ef64101ea60e17eaad74b4f42f789b695747 100644
--- a/build/bundle-component.js
+++ b/build/bundle-component.js
@@ -5,6 +5,7 @@ const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
 // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
 const bundleComponent = (loader, componentName) => {
     const componentPath = path.join(__dirname, `./components/${componentName}`);
+    console.log("teste");
     return loader.add(componentName, componentPath);
 };
 export default bundleComponent;
diff --git a/src/bundle-component.ts b/src/bundle-component.ts
index 28a36f32426f984f7aac103a3a45775671ab7891..d5d727e2b4059b2e4d2aa24be650a8bef374b306 100644
--- a/src/bundle-component.ts
+++ b/src/bundle-component.ts
@@ -12,6 +12,7 @@ const bundleComponent = (
   componentName: string,
 ) => {
   const componentPath = path.join(__dirname, `./components/${componentName}`)
+  console.log("teste")
   return loader.add(componentName, componentPath)
 }

Lembre-se de dar commit do arquivo de patch gerado, só assim você conseguirá reutilizar em futuras instalações.

Conclusão

Hoje vimos como fazer um patch de uma lib e como buildar ela para que as alterações sejam aplicadas. Também vimos que o Yarn V2 e o pnpm tem soluções nativas para esse problema, e que o patch-package ainda é uma boa solução para quem não quer migrar para o Yarn V2 ou pnpm.

E você ja passou por isso? Compartilhe outras ideias e conhecimentos ai sobre codar libs!

Implementando SSR com React e Express

Caio Fuzatto — Thu, 28 Sep 2023 20:24:30 +0000

Fala galera, hoje estou com a ideia de criar meu próprio servidor de React utilizando ExpressJS. A ideia é criar a lógica de SSR com as apis do React e utilizar o Express para cuidar das rotas e do servidor. Vamos nessa?

Se você quiser entender os conceitos que estamos utilizando aqui, recomendo que leia o meu post sobre o Universo de renderização do React.

Criando o projeto

Bom galera criei uma pasta chamada react-ssr e comecei rodando yarn init para criar o projeto. Depois disso instalei as dependências do express e do react com yarn add express react react-dom.

Typescript

Para utilizar o typescript no projeto, instalei as dependências com:

yarn add -D typescript @types/react @types/react-dom @types/express

Depois disso criei o arquivo tsconfig.json com o comando npx tsc --init. As minhas configurações do typescript ficaram assim:

{
  "compilerOptions": {
    "target": "ESNext",
    "jsx": "react",                                
    "module": "CommonJS",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  }
}

Testando a instalação

Agora para testar a instalação vamos fazer um hello world. Crie o arquivo index.html com o seguinte código:

<!DOCTYPE html>
<html lang="pt-br">
  <head>
    <title>Meu React App</title>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

Observe que nosso HTML é bem semelhante ao que vem na pasta public de uma instalação feita com create-react-app.

Agora vamos criar nosso primeiro componente React. Crie o arquivo App.tsx e cole o código abaixo:

import React from 'react'

export const App = () => {
  return (
    <div>
      <h1>Hello world</h1>
    </div>
  );
}

Por fim vamos criar o arquivo index.ts que será o arquivo principal do nosso servidor React com Express, cole o seguinte código:

import path from "path";
import fs from "fs";

import React from "react";
import ReactDOMServer from "react-dom/server";
import express from "express";

import { App } from "./App";

const app = express();

app.get("/", (req, res) => {
  const appContent = ReactDOMServer.renderToString(React.createElement(App));
  const indexFile = path.resolve("./index.html");

  fs.readFile(indexFile, "utf8", (err, data) => {
    if (err) {
      return res.status(500).send("Não foi possível carregar o app.");
    }

    return res.send(
      data.replace('<div id="root"></div>', `<div id="root">${appContent}</div>`)
    );
  });
});

app.listen(8080, () => {
  console.log(`App rodando na porta ${8080}`);
});

Para testar vamos rodar npx ts-node index.ts e acessar o localhost:8080. Se tudo deu certo, você deve ver o hello world na tela:

Até esse momento criamos uma implementação básica simulando um SSR. Basicamente a gente está pegando um HTML base que é nosso index.html e substituindo o conteúdo da div root pelo conteúdo do nosso componente App que foi gerado utilizando o ReactDOMServer.renderToString.

Hidratação do HTML

Nesse ponto já temos uma implementação básica de SSR, mas ainda não temos a hidratação, ou seja, até aqui o React está 100% no servidor, se a gente adicionar um evento no botão, utilizando um useState por exemplo, ele não vai funcionar. Então vamos fazer a hidratação do nosso HTML. Vamos começar criando um componente React que utiliza um hook client-side para nosso teste. Altere o arquivo App.tsx para o seguinte:

import React from 'react'

export const App = () => {
  const [state, setState] = React.useState(0);

  const count = () => {
    const newState = state + 1
    setState(newState);
    console.log(newState)
  }

  return (
    <div>
      <h1>Counter: {state}</h1>
      <button onClick={count}>Counter</button>
    </div>
  );
}

Instalando e configurando o webpack

O Webpack é uma ferramenta que nos permite fazer o bundling do nosso código, ou seja, ele vai pegar todos os nossos arquivos e juntar em um só arquivo. Isso é muito útil para o browser, pois ele só precisa fazer uma requisição para o servidor e não várias. Nesse caso vamos utilizar o webpack para gerar um arquivo bundle.js que vai conter todo o nosso código React em Javascript.

Antes de tudo vamos a uma pequena reorganização dos nossos arquivos:

Vamos mover o arquivo App.tsx para a pasta src/client/App.tsx
O arquivo index.ts para a pasta src/server/index.ts.

Para instalar as dependências do webpack rode o comando:

yarn add --dev ts-loader webpack webpack-cli

Agora vamos criar o arquivo webpack.config.js com o seguinte conteúdo:

const path = require("path");

const clientConfig = {
  mode: "development",
  target: "web",
  entry: "./src/client/index.tsx",
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: "ts-loader",
        exclude: /node_modules/,
      },
    ],
  },
  resolve: {
    extensions: [".tsx", ".ts", ".js"],
  },
  output: {
    filename: "bundle.js",
    path: path.resolve(__dirname, "dist/public"),
  },
};

const serverConfig = {
  mode: "development",
  entry: "./src/server/index.ts",
  target: "node",
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: "ts-loader",
        exclude: /node_modules/,
      },
    ],
  },
  resolve: {
    extensions: [".tsx", ".ts", ".js"],
  },
  output: {
    filename: "index.js",
    path: path.resolve(__dirname, "dist"),
  },
};

module.exports = [clientConfig, serverConfig];

Estamos configurando o webpack para gerar dois arquivos, um para o client e outro para o server. O arquivo do client vai ser gerado na pasta dist/public e o do server na pasta dist.

Melhorando o ambiente de desenvolvimento

Para facilitar nossa vida vamos instalar duas libs que são ótimas no ambiente de desenvolvimento. A primeira é a nodemon que vai ficar observando nossos arquivos e reiniciando o servidor sempre que houver alguma alteração. A segunda é a concurrently que vai nos permitir rodar o webpack e o nodemon ao mesmo tempo utilizando um só comando. Para instalar as dependências rode o comando:

yarn add --dev nodemon concurrently

Com as libs instaladas, bora criar nosso primeiro script. No seu package.json, adicione:

  "scripts": {
    "dev": "webpack && concurrently \"webpack --watch\" \"nodemon dist\""
  },

E seu tudo deu certo, agora é só rodar yarn dev e temos um counter funcionando:

Streaming SSR

Vamos dar um passo além e fazer o streaming do SSR, funcionalidade que é o coração do React Server Components. Primeiro vamos alterar nossa rota do express para funcionar como um socket e nossa resposta vai ser um stream. Para isso vamos utilizar o método ReactDOMServer.renderToPipeableStream. Altere o arquivo src/server/index.ts para o seguinte:

// ...
app.get('/', (req, res) => {
  res.socket.on('error', (error) => console.log('Fatal', error));

  let didError = false;
  const stream = ReactDOMServer.renderToPipeableStream(
      React.createElement(App),
      {
          bootstrapScripts: ['/bundle.js'],
          onShellReady: () => {
              res.statusCode = didError ? 500 : 200;
              res.setHeader('Content-type', 'text/html');
              stream.pipe(res);
          },
          onError: (error) => {
              didError = true;
              console.log(error);
          } 
      }
  );
});
// ...

E também vamos criar nosso componente que será renderizado no lado do servidor. Crie um novo arquivo src/client/HeavyComponent.tsx com o seguinte conteúdo:

import React from "react";
let status = "pending";
let result = null;

const asyncFunc = (func: Promise<any>) => {
  const fetching = func
    .then((success) => {
      status = "fulfilled";

      result = success;
    })
    .catch((error) => {
      status = "rejected";

      result = error;
    });

  if (status === "pending") {
    throw fetching;
  } else if (status === "rejected") {
    throw result;
  } else if (status === "fulfilled") {
    return result;
  }
};

export default function HeavyComponent() {
  const data = asyncFunc(getData());

  async function getData() {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    return { username: "itsmicaio" };
  }
  return (
    <div>
      <h3>Demorei mas carreguei!</h3>
      <p>{JSON.stringify(data)}</p>
    </div>
  );
}

Declaramos a variável status="pending" que será utilizada para informar ao React o estado da promessa. Enquanto estiver pendente o React vai renderizar o fallback da Suspense API.

A função asyncFunc é uma função que simula uma chamada assíncrona. Ela recebe uma promise e retorna o resultado dela. Se a promise ainda não foi resolvida, ela lança um erro que é capturado pelo React e renderiza o fallback. Se a promise já foi resolvida, ela retorna o resultado.

Finalmente nossa função que busca os dados. Ela é uma função assíncrona que espera 5 segundos e retorna um objeto com o meu username.

Pra gente conseguir ver a magica acontecendo, vamos utilizar a Suspense API junto com o HeavyComponent. Altere o arquivo App.tsx para o seguinte:

import React, { lazy, Suspense } from "react";
const HeavyComponent = lazy(() => import("./HeavyComponent"));

export const App = () => {
  return (
    <div id="root">
      <h1>Test suspense</h1>
      <Suspense fallback={<h3>Carregando...</h3>}>
        <HeavyComponent />
      </Suspense>
      <Counter />
    </div>
  );
};

E é só dar um reload na página e vamos conseguir ver nosso componente sendo carregado e posteriormente renderizado na página:

Explicando o HTML final

Se você olhar o HTML final que foi gerado, vai ver que ele está bem diferente do que a gente tinha antes. Agora temos um comentário  que indica o inicio do nosso componente e um comentário  que indica o fim do nosso componente. E no meio desses comentários temos um template com um id que é onde o nosso componente deve ser inserido após o carregamento.

<div>
    <h1>Test suspense</h1>
    <!--$?-->
    <template id="B:0"></template>
    <h3>Carregando...</h3>
    <!--/$-->
    <div id="counter">
        <h1>Counter: 
        <!-- -->
        0</h1>
        <button>Counter</button>
    </div>
</div>
<script src="/bundle.js" async=""></script>
<div hidden id="S:0">
    <div>
        <h3>Demorei mas carreguei!</h3>
        <p>{&quot;username &quot;:&quot;itsmicaio &quot;}</p>
    </div>
</div>
<script>
    function $RC(a, b) {
        a = document.getElementById(a);
        b = document.getElementById(b);
        b.parentNode.removeChild(b);
        if (a) {
            a = a.previousSibling;
            var f = a.parentNode
              , c = a.nextSibling
              , e = 0;
            do {
                if (c && 8 === c.nodeType) {
                    var d = c.data;
                    if ("/$" === d)
                        if (0 === e)
                            break;
                        else
                            e--;
                    else
                        "$" !== d && "$?" !== d && "$!" !== d || e++
                }
                d = c.nextSibling;
                f.removeChild(c);
                c = d
            } while (c);
            for (; b.firstChild; )
                f.insertBefore(b.firstChild, c);
            a.data = "$";
            a._reactRetry && a._reactRetry()
        }
    }
    ;$RC("B:0", "S:0")
</script>

No final do HTML também temos um script que é responsável por fazer a inserção do nosso componente no HTML. Ele basicamente pega o template com o id B:0 e substitui pelo conteúdo da div com o id S:0 que é justamente o componente carregado no servidor.

Conclusão

Viu só que legal? Deu pra entender de forma mais profunda como funciona as formas de renderização de React e algumas implementações que estão acontecendo por de baixo dos panos em ferramentas como NextJS e Gatsby. É claro que essa é uma implementação bem simples e não recomendo que você utilize em produção, mas é uma ótima forma de entender como as coisas funcionam.

Você pode ver o código completo no github e também pode ver o artigo que fiz explicando o Universo de renderização do React. Fui :p