Forem: Felipe Rohde

De Next.js a React Edge com Cloudflare Workers: Uma História de Libertação

Felipe Rohde — Mon, 18 Nov 2024 18:58:44 +0000

A Gota D'água
A Alternativa com Cloudflare 😍
React Edge: O Framework React derivado de todas (ou quase) as dores de um desenvolvedor
- A Magia do RPC Tipado
- O Poder do useFetch: Onde a Mágica Acontece
Além do useFetch: O arsenal completo
- RPC: A Arte da Comunicação Cliente-Servidor
- Um Sistema de i18n que Faz Sentido
- Autenticação JWT que "Simplesmente Funciona"
- O Store Compartilhado
- Roteamento Elegante
- Cache Distribuído com Edge Cache
Link: O Componente que Pensa à Frente
app.useContext: O Portal para o Edge
app.useUrlState: Estado Sincronizado com a URL
app.useStorageState: Estado Persistente
app.useDebounce: Controle de Frequência
app.useDistinct: Estado sem Duplicatas
A CLI do React Edge: Potência na Ponta dos Dedos
Conclusão

A Gota D'água

Tudo começou com uma fatura da Vercel. Não, na verdade começou bem antes - com pequenas frustrações que foram se acumulando. A necessidade de pagar por features básicas como proteção DDoS, logs mais detalhados, ou mesmo um firewall decente, filas de builds, etc. A sensação de estar preso em um vendor lock-in cada vez mais caro.

"E o pior de tudo: nossos preciosos cabeçalhos de SEO simplesmente deixaram de ser renderizados no servidor em uma aplicação utilizando o pages router. Uma verdadeira dor de cabeça para qualquer dev! 😭"

Mas o que realmente me fez repensar tudo foi a direção que o Next.js estava tomando. A introdução do use client, use server - diretivas que, em teoria, deveriam simplificar o desenvolvimento, mas na prática adicionavam mais uma camada de complexidade para gerenciar. Era como se estivéssemos voltando aos tempos do PHP, marcando arquivos com diretivas para dizer onde eles deveriam rodar.

E não para por aí. O App Router, uma ideia interessante, mas implementada de forma que criou um framework praticamente novo dentro do Next.js. De repente, tínhamos duas formas completamente diferentes de fazer a mesma coisa. A 'velha' e a 'nova' - com comportamentos sutilmente diferentes e armadilhas escondidas.

A Alternativa com Cloudflare 😍

Foi quando percebi: por que não aproveitar a incrível infraestrutura da Cloudflare com Workers rodando no edge, R2 para storage, KV para dados distribuídos... Além, é claro, a incrível proteção DDoS, CDN global, firewall, regras par páginas e rotas e tudo mais que a Cloudflare oferece.

E o melhor: um modelo de preço justo, onde você paga pelo que usa, sem surpresas.

Assim nasceu o React Edge. Um framework que não tenta reinventar a roda, mas sim proporcionar uma experiência de desenvolvimento verdadeiramente simples e moderna.

React Edge: O Framework React derivado de todas (ou quase) as dores de um desenvolvedor

Quando comecei a desenvolver o React Edge, tinha um objetivo claro: criar um framework que fizesse sentido. Não mais lutar com diretivas confusas, não mais pagar fortunas por recursos básicos, e principalmente, não mais ter que lidar com a complexidade artificial criada pela separação cliente/servidor. Eu queria velocidade, algo que entregasse performance sem sacrificar simplicidade. Aproveitando meu conhecimento da API do React e anos como desenvolvedor Javascript e Golang, sabia exatamente como lidar com streams e multiplexação para otimizar a renderização e o gerenciamento de dados.

O Cloudflare Workers, com sua infraestrutura poderosa e presença global, me ofereceu o ambiente perfeito para explorar essas possibilidades. Queria algo que fosse verdadeiramente híbrido, e essa combinação de ferramentas e experiência foi o que deu vida ao React Edge: um framework que resolve problemas reais com soluções modernas e eficientes.

O React Edge traz uma abordagem revolucionária para desenvolvimento React. Imagine poder escrever uma classe no servidor e chamá-la diretamente do cliente, com tipagem completa e zero configuração. Imagine um sistema de cache distribuído que "simplesmente funciona", permitindo invalidação por tags ou prefixos. Imagine poder compartilhar estado entre servidor e cliente de forma transparente e segura. Além de simplificar a autenticação e trazer uma abordagem de internacionalização eficiente, CLI e muito mais.

Sua comunicação RPC é tão natural que parece mágica - você escreve métodos em uma classe e os chama do cliente como se fossem locais. O sistema de multiplexação inteligente garante que, mesmo que múltiplos componentes façam a mesma chamada, apenas uma requisição seja feita ao servidor. O cache efêmero evita requisições repetidas desnecessárias, e tudo isso funciona tanto no servidor quanto no cliente.

Um dos pontos mais poderosos é o hook app.useFetch, que unifica a experiência de data fetching. No servidor, ele pré-carrega os dados durante o SSR; no cliente, ele hidrata automaticamente com esses dados e permite atualizações sob demanda. E com suporte a polling automático e reatividade baseada em dependências, criar interfaces dinâmicas nunca foi tão fácil.

Mas não para por aí. O framework oferece um sistema de rotas poderoso (inspirado no fantástico Hono), gerenciamento de assets integrado com Cloudflare R2, e uma forma elegante de lidar com erros através da classe HttpError. Os middlewares podem facilmente enviar dados para o cliente através de um store compartilhado, e tudo é ofuscado automaticamente para segurança.

O mais impressionante? Quase todo o código do framework é híbrido. Não há uma versão 'cliente' e outra 'servidor' - o mesmo código funciona nos dois ambientes, adaptando-se automaticamente ao contexto. O cliente recebe apenas o que precisa, tornando o bundle final extremamente otimizado.

E a cereja do bolo: tudo isso roda na infraestrutura edge do Cloudflare Workers, proporcionando performance excepcional a um custo justo. Sem surpresas na fatura, sem recursos básicos escondidos atrás de planos enterprise forçados, apenas um framework sólido que permite você focar no que realmente importa: criar aplicações incríveis. Além disso, o React Edge aproveita todo o ecossistema da Cloudflare, incluindo Queues, Durable Objects, KV Storage, e muito mais para oferecer uma base robusta e escalável para suas aplicações.

O Vite foi usado como base, tanto para o ambiente de desenvolvimento quanto para testes e build. O Vite, com sua velocidade impressionante e arquitetura moderna, permite um fluxo de trabalho ágil e eficiente. Ele não apenas acelera o desenvolvimento, mas também otimiza o processo de build, garantindo que o código seja compilado de forma rápida e precisa. Sem dúvida, o Vite foi a escolha perfeita para o React Edge.

Repensando o Desenvolvimento React para a era do Edge Computing

Você já se perguntou como seria desenvolver aplicações React sem se preocupar com a barreira cliente/servidor? Sem precisar decorar dezenas de diretivas como use client ou use server? E melhor ainda: e se você pudesse chamar funções do servidor como se fossem locais, com tipagem completa e zero configuração?

Com o React Edge, você não precisa:

Criar rotas de API separadas
Gerenciar estado de loading/error manualmente
Implementar debounce na mão
Se preocupar com serialização/deserialização
Lidar com CORS
Gerenciar tipagem entre cliente/servidor
Lidar com regras de autenticação manualmente
Gerenciar como a internacionalização é feita

E o melhor: tudo isso funciona tanto no servidor quanto no cliente, sem precisar marcar nada com use client ou use server. O framework sabe o que fazer baseado no contexto. Vamos lá?

A Magia do RPC Tipado

Imagine poder fazer isso:

// No servidor
class UserAPI extends Rpc {
  async searchUsers(query: string, filters: UserFilters) {
    // Validação com Zod
    const validated = searchSchema.parse({ query, filters });
    return this.db.users.search(validated);
  }
}

// No cliente
const UserSearch = () => {
  const { rpc } = app.useContext<App.Context>();

  // TypeScript sabe exatamente o que searchUsers aceita e retorna!
  const { data, loading, error, fetch: retry } = app.useFetch(
    async (ctx) => ctx.rpc.searchUsers('John', { age: '>18' })
  );
};

Compare isso com o Next.js/Vercel:

// pages/api/search.ts
export default async handler = (req, res) => {
  // Configurar CORS
  // Validar request
  // Tratar erros
  // Serializar resposta
  // ...100 linhas depois...
}

// app/search/page.tsx
'use client';
import { useEffect, useState } from 'react';

export default const SearchPage = () => {
  const [search, setSearch] = useState('');
  const [filters, setFilters] = useState({});
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    let timeout;
    const doSearch = async () => {
      setLoading(true);
      try {
        const res = await fetch('/api/search?' + new URLSearchParams({
          q: search,
          ...filters
        }));
        if (!res.ok) throw new Error('Search failed');
        setData(await res.json());
      } catch (err) {
        console.error(err);
      } finally {
        setLoading(false);
      }
    };

    timeout = setTimeout(doSearch, 300);
    return () => clearTimeout(timeout);
  }, [search, filters]);

  // ... resto do componente
}

O Poder do useFetch: Onde a Mágica Acontece

Data Fetching Repensado

Esqueça tudo que você sabe sobre data fetching no React. O app.useFetch do React Edge traz uma abordagem completamente nova e poderosa. Imagine um hook que:

Pré-carrega dados no servidor durante SSR
Hidrata automaticamente no cliente sem flicker
Mantém tipagem completa entre cliente e servidor
Suporta reatividade com debounce inteligente
Multiplexa chamadas idênticas automaticamente
Permite atualizações programáticas e polling

Vamos ver isso em ação:

// Primeiro, definimos nossa API no servidor
class PropertiesAPI extends Rpc {
 async searchProperties(filters: PropertyFilters) {
   const results = await this.db.properties.search(filters);
   // Cache automático por 5 minutos
   return this.createResponse(results, {
     cache: { ttl: 300, tags: ['properties'] }
   });
 }

 async getPropertyDetails(ids: string[]) {
   return Promise.all(
     ids.map(id => this.db.properties.findById(id))
   );
 }
}

// Agora, no cliente, a mágica acontece
const PropertySearch = () => {
 const [filters, setFilters] = useState<PropertyFilters>({
   price: { min: 100000, max: 500000 },
   bedrooms: 2
 });

 // Busca reativa com debounce inteligente
 const { 
   data: searchResults,
   loading: searchLoading,
   error: searchError
 } = app.useFetch(
   async (ctx) => ctx.rpc.searchProperties(filters),
   {
     // Quando filters muda, refaz a busca
     deps: [filters],
     // Mas espera 300ms de 'silêncio' antes de buscar
     depsDebounce: {
       filters: 300
     }
   }
 );

 // Agora, vamos buscar os detalhes das propriedades encontradas
 const {
   data: propertyDetails,
   loading: detailsLoading,
   fetch: refreshDetails
 } = app.useFetch(
   async (ctx) => {
     if (!searchResults?.length) return null;

     // Isso parece fazer múltiplas chamadas, mas...
     return ctx.rpc.batch([
       // Na verdade, tudo é multiplexado em uma única requisição!
       ...searchResults.map(result => 
         ctx.rpc.getPropertyDetails(result.id)
       )
     ]);
   },
   {
     // Atualiza sempre que searchResults mudar
     deps: [searchResults]
   }
 );

 // Interface bonita e responsiva
 return (
   <div>
     <FiltersPanel 
       value={filters}
       onChange={setFilters}
       disabled={searchLoading}
     />

     {searchError && (
       <Alert status='error'>
         Erro na busca: {searchError.message}
       </Alert>
     )}

     <PropertyGrid
       items={propertyDetails || []}
       loading={detailsLoading}
       onRefresh={() => refreshDetails()}
     />
   </div>
 );
};

A Mágica da Multiplexação

O exemplo acima esconde uma característica poderosa: a multiplexação inteligente. Quando você usa ctx.rpc.batch, o React Edge não apenas agrupa as chamadas - ele deduplicar chamadas idênticas automaticamente:

const PropertyListingPage = () => {
  const { data } = app.useFetch(async (ctx) => {
    // Mesmo que você faça 100 chamadas idênticas...
    return ctx.rpc.batch([
      ctx.rpc.getProperty('123'),
      ctx.rpc.getProperty('123'), // mesma chamada
      ctx.rpc.getProperty('456'),
      ctx.rpc.getProperty('456'), // mesma chamada
    ]);
  });

  // Mas na realidade:
  // 1. O batch agrupa todas as chamadas em UMA única requisição HTTP
  // 2. Chamadas idênticas são deduplicas automaticamente
  // 3. O resultado é distribuído corretamente para cada posição do array
  // 4. A tipagem é mantida para cada resultado individual!


  // Entao..
  // 1. getProperty('123')
  // 2. getProperty('456')
  // E os resultados são distribuídos para todos os chamadores!
};

SSR + Hidratação Perfeita

Uma das partes mais impressionantes é como o useFetch lida com SSR:

const ProductPage = ({ productId }: Props) => {
  const { data, loaded, loading, error } = app.useFetch(
    async (ctx) => ctx.rpc.getProduct(productId),
    {
      // Controle fino de quando executar
      shouldFetch: ({ worker, loaded }) => {
        // No worker (SSR): sempre busca
        if (worker) return true;
        // No cliente: só busca se não tiver dados
        return !loaded;
      }
    }
  );

  // No servidor:
  // 1. useFetch faz a chamada RPC
  // 2. Dados são serializados e enviados ao cliente
  // 3. Componente renderiza com os dados

  // No cliente:
  // 1. Componente hidrata com os dados do servidor
  // 2. Não faz nova chamada (shouldFetch retorna false)
  // 3. Se necessário, pode refazer a chamada com data.fetch()

  return (
    <Suspense fallback={<ProductSkeleton />}>
      <ProductView 
        product={data}
        loading={loading}
        error={error}
      />
    </Suspense>
  );
};

Além do useFetch: O arsenal completo

RPC: A Arte da Comunicação Cliente-Servidor

Segurança e Encapsulamento

O sistema RPC do React Edge foi projetado pensando em segurança e encapsulamento. Nem tudo que está em uma classe RPC é automaticamente exposto ao cliente:

class PaymentsAPI extends Rpc {
 // Propriedades nunca são expostas
 private stripe = new Stripe(process.env.STRIPE_KEY);

 // Métodos começando com $ são privados
 private async $validateCard(card: CardInfo) {
   return await this.stripe.cards.validate(card);
 }

 // Métodos começando com _ também são privados
 private async _processPayment(amount: number) {
   return await this.stripe.charges.create({ amount });
 }

 // Este método é público e acessível via RPC
 async createPayment(orderData: OrderData) {
   // Validação interna usando método privado
   const validCard = await this.$validateCard(orderData.card);
   if (!validCard) {
     throw new HttpError(400, 'Invalid card');
   }

   // Processamento usando outro método privado
   const payment = await this._processPayment(orderData.amount);
   return payment;
 }
}

// No cliente:
const PaymentForm = () => {
 const { rpc } = app.useContext<App.Context>();

 // ✅ Isso funciona
 const handleSubmit = () => rpc.createPayment(data);

 // ❌ Isso não é possível - métodos privados não são expostos
 const invalid1 = () => rpc.$validateCard(data);
 const invalid2 = () => rpc._processPayment(100);

 // ❌ Isso também não funciona - propriedades não são expostas
 const invalid3 = () => rpc.stripe;
};

Hierarquia de APIs RPC

Uma das características mais poderosas do RPC é a capacidade de organizar APIs em hierarquias:

// APIs aninhadas para melhor organização
class UsersAPI extends Rpc {
  // Subclasse para gerenciar preferences
  preferences = new UserPreferencesAPI();
  // Subclasse para gerenciar notificações
  notifications = new UserNotificationsAPI();

  async getProfile(id: string) {
    return this.db.users.findById(id);
  }
}

class UserPreferencesAPI extends Rpc {
  async getTheme(userId: string) {
    return this.db.preferences.getTheme(userId);
  }

  async setTheme(userId: string, theme: Theme) {
    return this.db.preferences.setTheme(userId, theme);
  }
}

class UserNotificationsAPI extends Rpc {
  // Métodos privados continuam privados
  private async $sendPush(userId: string, message: string) {
    await this.pushService.send(userId, message);
  }

  async getSettings(userId: string) {
    return this.db.notifications.getSettings(userId);
  }

  async notify(userId: string, notification: Notification) {
    const settings = await this.getSettings(userId);
    if (settings.pushEnabled) {
      await this.$sendPush(userId, notification.message);
    }
  }
}

// No cliente:
const UserProfile = () => {
  const { rpc } = app.useContext<App.Context>();

  const { data: profile } = app.useFetch(
    async (ctx) => {
      // Chamadas aninhadas são totalmente tipadas
      const [user, theme, notificationSettings] = await ctx.rpc.batch([
        // Método da classe principal
        ctx.rpc.getProfile('123'),
        // Método da subclasse de preferências
        ctx.rpc.preferences.getTheme('123'),
        // Método da subclasse de notificações
        ctx.rpc.notifications.getSettings('123')
      ]);

      return { user, theme, notificationSettings };
    }
  );

  // ❌ Métodos privados continuam inacessíveis
  const invalid = () => rpc.notifications.$sendPush('123', 'hello');
};

Benefícios da Hierarquia

Organizar APIs em hierarquias traz vários benefícios:

Organização Lógica: Agrupe funcionalidades relacionadas de forma intuitiva
Namespace Natural: Evite conflitos de nomes com caminhos claros (users.preferences.getTheme)
Encapsulamento: Mantenha métodos auxiliares privados em cada nível
Manutenibilidade: Cada subclasse pode ser mantida e testada independentemente
Tipagem Completa: O TypeScript entende toda a hierarquia

O sistema de RPC do React Edge torna a comunicação cliente-servidor tão natural que você quase esquece que está fazendo chamadas remotas. E com a capacidade de organizar APIs em hierarquias, você pode criar estruturas complexas mantendo o código organizado e seguro.

Um Sistema de i18n que Faz Sentido

O React Edge traz um sistema de internacionalização elegante e flexível, que suporta interpolação de variáveis e formatação complexa sem bibliotecas pesadas.

// translations/fr.ts
export default {
  'Good Morning, {name}!': 'Bonjour, {name}!',
};

Uso no código:

const WelcomeMessage = () => {
  const userName = 'João';

  return (
    <div>
      {/* Output: Bem vindo, João! */}
      <h1>{__('Good Morning, {name}!', { name: userName })}</h1>
  );
};

Configuração Zero

O React Edge detecta e carrega suas traduções automaticamente, podendo salvar fácilmente nos cookies a preferência do usuário. Mas isso você já esperava, certo?

// worker.ts
const handler = {
    fetch: async (request: Request, env: types.Worker.Env, context: ExecutionContext) => {
        const url = new URL(request.url);

        const lang = (() => {
            const lang =
                url.searchParams.get('lang') || worker.cookies.get(request.headers, 'lang') || request.headers.get('accept-language') || '';

            if (!lang || !i18n[lang]) {
                return 'en-us';
            }

            return lang;
        })();

        const worker = new AppWorkerEntry({
            i18n: {
                en: await import('./translations/en'),
                pt: await import('./translations/pt'),
                es: await import('./translations/es')
            }
        });

        const res = await workerApp.fetch();

        if (url.searchParams.has('lang')) {
            return new Response(res.body, {
                headers: worker.cookies.set(res.headers, 'lang', lang)
            });
        }

        return res;
    }
};

Autenticação JWT que "Simplesmente Funciona"

A autenticação sempre foi um ponto de dor em aplicações web. Gerenciar tokens JWT, cookies seguros, revalidação - tudo isso geralmente requer muito código boilerplate. O React Edge muda isso completamente.

Veja como é simples implementar um sistema completo de autenticação:

class SessionAPI extends Rpc {
 private auth = new AuthJwt({
   // Cookie será automaticamente gerenciado
   cookie: 'token',
   // Payload é automaticamente encriptado
   encrypt: true,
   // Expiração automática
   expires: { days: 1 },
   secret: process.env.JWT_SECRET
 });

 async signin(credentials: { 
   email: string; 
   password: string 
 }) {
   // Validação com Zod
   const validated = loginSchema.parse(credentials);
   const { headers } = await this.auth.sign(validated));

   // Retorna resposta com cookies configurados
   return this.createResponse(
     { email: validated.email },
     {
       headers: (await this.auth.sign(validated))
     }
   );
 }

 async getSession(revalidate = false) {
   // Validação e revalidação automática de token
   const { headers, payload } = await this.auth.authenticate(
     this.request.headers,
     revalidate
   );

   return this.createResponse(payload, { headers });
 }

 async signout() {
   // Limpa cookies automaticamente
   const { headers } = await this.auth.destroy();
   return this.createResponse(null, { headers });
 }
}

Uso no Cliente: Zero Configuração

const LoginForm = () => {
  const { rpc } = app.useContext<App.Context>();

  const login = async (values) => {
    const session = await rpc.signin(values);
    // Pronto! Cookies já estão setados automaticamente
  };

  return <Form onSubmit={login}>...</Form>;
};

const NavBar = () => {
  const { rpc } = app.useContext<App.Context>();

  const logout = async () => {
    await rpc.signout();
    // Cookies já foram limpos automaticamente
  };

  return <button onClick={logout}>Sair</button>;
};

Por Que Isso é Revolucionário?

Zero Boilerplate
- Sem gerenciamento manual de cookies
- Sem necessidade de interceptors
- Sem refresh tokens manual
Segurança por Padrão
- Tokens são automaticamente encriptados
- Cookies são seguros e httpOnly
- Revalidação automática
Tipagem Completa
- Payload do JWT é tipado
- Validação com Zod integrada
- Erros de autenticação tipados
Integração Perfeita

// Middleware que protege rotas
const authMiddleware: App.Middleware = async (ctx) => {
  const session = await ctx.rpc.session.getSession();

  if (!session) {
    throw new HttpError(401, 'Unauthorized');
  }

  // Disponibiliza sessão para componentes
  ctx.store.set('session', session, 'public');
};

// Uso em rotas
const router: App.Router = {
  routes: [
    routerBuilder.routeGroup({
      path: '/dashboard',
      middlewares: [authMiddleware],
      routes: [/*...*/]
    })
  ]
};

O Store Compartilhado

Uma das features mais poderosas do React Edge é sua capacidade de compartilhar estado entre worker e cliente de forma segura. Vamos ver como isso funciona:

// middleware/auth.ts
const authMiddleware: App.Middleware = async (ctx) => {
  const token = ctx.request.headers.get('authorization');

  if (!token) {
    throw new HttpError(401, 'Unauthorized');
  }

  const user = await validateToken(token);

  // Dados públicos - automaticamente compartilhados com o cliente
  ctx.store.set('user', {
    id: user.id,
    name: user.name,
    role: user.role
  }, 'public');

  // Dados privados - permanecem apenas no worker mas
  ctx.store.set('userSecret', user.secret);
};

// components/Header.tsx
const Header = () => {
  // Acesso transparente aos dados do store
  const { store } = app.useContext();
  const user = store.get('user');

  return (
    <header>
      <h1>Bem vindo, {user.name}!</h1>
      {user.role === 'admin' && (
        <AdminPanel />
      )}
    </header>
  );
};

Como Funciona

Dados Públicos: Os dados marcados como públicos são compartilhados de forma segura com o cliente, tornando-os facilmente acessíveis para os componentes.
Dados Privados: Os dados sensíveis permanecem dentro do ambiente do worker e nunca são expostos ao cliente.
Integração com Middleware: O middleware pode popular a store com dados públicos e privados, garantindo um fluxo contínuo de informações entre a lógica do servidor e a renderização do lado do cliente.

Benefícios

Segurança: A separação dos escopos de dados públicos e 2. privados garante que as informações sensíveis permaneçam protegidas.
Conveniência: O acesso transparente aos dados da store simplifica o gerenciamento de estado entre worker e cliente.
Flexibilidade: A store é facilmente integrada com middleware, permitindo atualizações dinâmicas de estado baseadas no tratamento de requisições.

Roteamento Elegante

O sistema de rotas do React Edge é inspirado no Hono, mas com superpoderes para SSR:

const router: App.Router = {
  routes: [
    routerBuilder.routeGroup({
      path: '/dashboard',
      // Middlewares aplicados a todas rotas do grupo
      middlewares: [authMiddleware, dashboardMiddleware],
      routes: [
        routerBuilder.route({
          path: '/',
          handler: {
            page: {
              value: DashboardPage,
              // Headers específicos para esta rota
              headers: new Headers({
                'Cache-Control': 'private, max-age=0'
              })
            }
          }
        }),
        routerBuilder.route({
          path: '/api/stats',
          handler: {
            // Rotas podem retornar respostas diretas
            response: async (ctx) => {
              const stats = await ctx.rpc.stats.getDashboardStats();
              return {
                value: Response.json(stats),
                // Cache por 5 minutos
                cache: { ttl: 300 }
              };
            }
          }
        })
      ]
    })
  ]
};

Principais Recursos

Rotas Agrupadas: Agrupamento lógico de rotas relacionadas sob um caminho e middleware compartilhados. Manipuladores Flexíveis: Defina manipuladores que retornam páginas ou respostas diretas da API.
Cabeçalhos por Rota: Personalize cabeçalhos HTTP para rotas individuais.
Cache Integrado: Simplifique estratégias de cache com ttl e tags.

Benefícios

Consistência: Ao agrupar rotas relacionadas, você garante a aplicação consistente de middleware e organização do código.
Escalabilidade: O sistema suporta roteamento aninhado e modular para aplicações em grande escala.
Desempenho: Suporte nativo para cache garante tempos de resposta ideais sem configurações manuais.

Cache Distribuído com Edge Cache

O React Edge possui um sistema de cache poderoso que funciona tanto para dados JSON quanto para páginas inteiras:

class ProductsAPI extends Rpc {
  async getProducts(category: string) {
    const products = await this.db.products.findByCategory(category);

    return this.createResponse(products, {
      cache: {
        ttl: 3600, // 1 hora
        tags: [`category:${category}`, 'products']
      }
    });
  }

  async updateProduct(id: string, data: ProductData) {
    await this.db.products.update(id, data);

    // Invalida cache específico do produto e sua categoria
    await this.cache.deleteBy({
      tags: [
        `product:${id}`,
        `category:${data.category}`
      ]
    });
  }

  async searchProducts(query: string) {
    const results = await this.db.products.search(query);

    // Cache com prefixo para fácil invalidação
    return this.createResponse(results, {
      cache: {
        ttl: 300,
        tags: [`search:${query}`]
      }
    });
  }
}

// Em qualquer lugar do código:
await cache.deleteBy({
  // Invalida todos resultados de busca
  keyPrefix: 'search:',
  // E todos produtos de uma categoria
  tags: ['category:electronics']
});

Principais Recursos

Invalidação Baseada em Tags: Entradas de cache podem ser agrupadas usando tags, permitindo invalidação fácil e seletiva quando os dados são alterados.
Correspondência por Prefixo: Invalide várias entradas de cache usando um prefixo comum, ideal para cenários como consultas de pesquisa ou dados hierárquicos.
Tempo de Vida (TTL): Defina tempos de expiração para entradas de cache para garantir dados atualizados mantendo alto desempenho.

Benefícios

Desempenho Aprimorado: Reduz a carga nas APIs ao fornecer respostas em cache para dados frequentemente acessados.
Escalabilidade: Gerencia eficientemente grandes conjuntos de dados e alto tráfego com um sistema de cache distribuído.
Flexibilidade: Controle refinado sobre o cache, permitindo que desenvolvedores otimizem o desempenho sem sacrificar a precisão dos dados.

Link: O Componente que Pensa à Frente

O componente Link é uma solução inteligente e performática para pré-carregar recursos no lado cliente, garantindo uma navegação mais fluida e rápida para os usuários. Sua funcionalidade de prefetching é ativada ao passar o cursor sobre o link, aproveitando o momento de inatividade do usuário para requisitar antecipadamente os dados do destino.

Como Funciona?

Prefetch Condicional: O atributo prefetch (ativo por padrão) controla se o pré-carregamento será realizado.
Cache Inteligente: Um conjunto (Set) é usado para armazenar os links já pré-carregados, evitando chamadas redundantes.
Mouse Enter: Quando o usuário passa o cursor sobre o link, a função handleMouseEnter verifica se o pré-carregamento é necessário e, caso positivo, inicia uma requisição fetch para o destino.
Erro Seguro: Qualquer falha na requisição é suprimida, garantindo que o comportamento do componente não seja afetado por erros momentâneos de rede.

<app.Link href=`/about` prefetch>
  Sobre Nós
</app.Link>

Quando o usuário passar o mouse sobre o link “Sobre Nós”, o componente já começará a pré-carregar os dados da página /about, proporcionando uma transição quase instantânea. Idéia genial, não? Mas vi na documentação do react.dev.

app.useContext: O Portal para o Edge

O app.useContext é o hook fundamental do React Edge, proporcionando acesso a todo contexto do worker:

const DashboardPage = () => {
 const {
   // Parâmetros da rota atual
   pathParams,
   // Query params (já parseados)
   searchParams,
   // Rota que deu match
   path,
   // Rota original (com parâmetros)
   rawPath,
   // Proxy para RPC
   rpc,
   // Store compartilhado
   store,
   // URL completa
   url
 } = app.useContext<App.Context>();

 // Tipagem completa do RPC
 const { data } = app.useFetch(
   async (ctx) => ctx.rpc.getDashboardStats()
 );

 // Acesso aos dados do store
 const user = store.get('user');

 return (
   <div>
     <h1>Dashboard para {user.name}</h1>
     <p>Visualizando: {path}</p>
   </div>
 );
};

Principais Recursos do app.useContext

Gerenciamento de Rotas: Obtenha acesso à rota correspondente, seus parâmetros e strings de consulta sem esforço.
Integração RPC: Faça chamadas RPC tipadas e seguras diretamente do cliente sem configuração adicional.
Acesso à Store Compartilhada: Recupere ou defina valores no estado compartilhado worker-cliente com controle total sobre a visibilidade (público/privado).
Acesso Universal à URL: Acesse facilmente a URL completa da requisição atual para renderização e interações dinâmicas.

Por Que É Poderoso

O hook app.useContext preenche a lacuna entre o worker e o cliente. Ele permite que você construa recursos que dependem de estado compartilhado, busca segura de dados e renderização contextual sem código repetitivo. Isso simplifica aplicações complexas, tornando-as mais fáceis de manter e mais rápidas de desenvolver.

app.useUrlState: Estado Sincronizado com a URL

O hook app.useUrlState mantém o estado da sua aplicação sincronizado com os parâmetros da URL, oferecendo controle preciso sobre o que é incluído na URL, como o estado é serializado e quando é atualizado.

const ProductsPage = () => {
  // Estado automaticamente sincronizado com query params
  const [filters, setFilters] = app.useUrlState({
      categoria: 'todos',
      precoMinimo: 0,
      precoMaximo: 1000,
      outros: {
          foo: 'bar',
          baz: 'qux'
      }
  }, {
      debounce: 500,              // Atrasa atualizações da URL em 500ms
      kebabCase: true,            // Converte chaves para kebab-case para URLs mais limpas
      omitKeys: ['filtro.locais'], // Exclui chaves específicas da URL
      omitValues: [],             // Exclui valores específicos da URL
      pickKeys: [],               // Inclui apenas chaves específicas na URL
      prefix: '',                 // Adiciona um prefixo opcional às chaves de consulta
      url: ctx.url                // Usa a URL atual do contexto (funciona no servidor)
  });

  const { data } = app.useFetch(
    async (ctx) => ctx.rpc.produtos.buscar(filters),
    {
      // Refetch quando filters mudar
      deps: [filters]
    }
  );

  return (
    <div>
      <PainelFiltros
        value={filters}
        onChange={(novosFiltros) => {
          // URL é atualizada automaticamente
          setFilters(novosFiltros);
        }}
      />
      <GradeProdutos data={data} />
    </div>
  );
};

Parâmetros

Estado Inicial
- Um objeto definindo a estrutura padrão e valores para seu estado.
Opções:
- debounce: Controla a rapidez com que a URL é atualizada após mudanças de estado.
- kebabCase: Converte chaves de estado para kebab-case ao serializar para a URL.
- omitKeys: Especifica chaves a serem excluídas da URL.
- omitValues: Valores que, quando presentes, excluirão a chave associada da URL.
- pickKeys: Limita o estado serializado para incluir apenas chaves específicas.
- prefix: Adiciona um prefixo a todos os parâmetros de consulta.
- url: A URL base para sincronização, geralmente derivada do contexto da aplicação.

Benefícios

Amigável para SEO: Garante que visualizações dependentes de estado sejam refletidas em URLs compartilháveis.
Atualizações com Debounce: Previne atualizações excessivas de consultas para entradas que mudam rapidamente.
URLs Limpas: Opções como kebabCase e omitKeys mantêm as strings de consulta legíveis.
Hidratação de Estado: Inicializa automaticamente o estado da URL na montagem do componente.
Funciona em todos ambientes: Suporta renderização no servidor e navegação no cliente.

Aplicações Práticas

Filtros para Listagens: Sincroniza filtros aplicados pelo usuário com a URL.
Visualizações Dinâmicas: Garante que zoom do mapa, pontos centrais ou outras configurações persistam.
Preferências do Usuário: Salva configurações selecionadas na URL para compartilhamento.

app.useStorageState: Estado Persistente

O hook app.useStorageState permite persistir estado no navegador usando localStorage ou sessionStorage com suporte completo a tipagem.

type RecentSearch = {
  term: string;
  date: string;
  category: string;
}

type SearchState {
  recentSearches: RecentSearch[];
  favorites: string[];
  lastSearch?: string;
}

const RecentSearches = () => {
  // Inicializa o estado com tipagem e valores padrão
  const [searchState, setSearchState] = app.useStorageState<SearchState>(
    // Chave única para armazenamento
    'user-searches',
    // Estado inicial
    {
      recentSearches: [],
      favorites: [],
      lastSearch: undefined
    },
    // Opções de configuração
    {
      // Atrasa a gravação no storage por 500ms para otimizar performance
      debounce: 500,

      // Define o tipo de armazenamento:
      // 'local' - persiste mesmo após fechar o navegador
      // 'session' - persiste apenas durante a sessão
      storage: 'local',

      // Ignora estas chaves ao salvar no storage
      omitKeys: ['lastSearch'],

      // Salva apenas estas chaves específicas
      pickKeys: ['recentSearches', 'favorites']
    }
  );

  return (
    <div className="recent-searches">
      <h3>Buscas Recentes</h3>

      {/* Lista as buscas recentes */}
      <ul>
        {searchState.recentSearches.map((search, index) => (
          <li key={index}>
            <span>{search.term}</span>
            <small>{search.date}</small>

            {/* Botão para favoritar busca */}
            <button
              onClick={() => {
                setSearchState({
                  ...searchState,
                  favorites: [...searchState.favorites, search.term]
                })
              }}
            >
              ⭐
            </button>
          </li>
        ))}
      </ul>

      {/* Botão para limpar histórico */}
      <button
        onClick={() => {
          setSearchState({
            ...searchState,
            recentSearches: []
          })
        }}
      >
        Limpar Histórico
      </button>
    </div>
  );
};

Opções de Persistência

debounce: Controla frequência de gravação
storage: Escolha entre localStorage e sessionStorage
omitKeys/pickKeys: Controle fino sobre dados persistidos

Performance

Atualizações otimizadas com debounce
Serialização/deserialização automática
Cache em memória

Casos de Uso Comuns

Histórico de pesquisas
Lista de favoritos
Preferências do usuário
Estado de filtros
Carrinho de compras temporário
Rascunhos de formulários

app.useDebounce: Controle de Frequência

Debounce valores reativos com facilidade:

const SearchInput = () => {
  const [input, setInput] = useState('');

  // Valor debounced atualiza apenas após 300ms de 'silêncio'
  const debouncedValue = app.useDebounce(input, 300);

  const { data } = app.useFetch(
    async (ctx) => ctx.rpc.search(debouncedValue),
    {
      // Fetch acontece apenas quando o valor debounced muda
      deps: [debouncedValue]
    }
  );

  return (
    <div>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        placeholder='Buscar...'
      />
      <SearchResults data={data} />
    </div>
  );
};

app.useDistinct: Estado sem Duplicatas

Mantenha arrays de valores únicos com tipagem:

O app.useDistinct é um hook especializado em detectar quando um valor realmente mudou, com suporte a comparação profunda e debounce:

const SearchResults = () => {
  const [search, setSearch] = useState('');

  // Detecta mudanças distintas no valor de busca
  const {
    value: currentSearch,   // Valor atual
    prevValue: lastSearch,  // Valor anterior
    distinct: hasChanged    // Indica se houve mudança
  } = app.useDistinct(search, {
    // Debounce de 300ms
    debounce: 300,
    // Comparação profunda
    deep: true,
    // Função de comparação customizada
    compare: (a, b) => a?.toLowerCase() === b?.toLowerCase()
  });

  // Fetch apenas quando a busca realmente mudar
  const { data } = app.useFetch(
    async (ctx) => ctx.rpc.search(currentSearch),
    {
      deps: [currentSearch],
      // Só executa se houve mudança distinta
      shouldFetch: () => hasChanged
    }
  );

  return (
    <div>
      <input
        value={search}
        onChange={(e) => setSearch(e.target.value)}
      />

      {hasChanged && (
        <small>
          Busca alterada de '{lastSearch}' para '{currentSearch}'
        </small>
      )}

      <SearchResults data={data} />
    </div>
  );
};

Principais Recursos

Detecção de Valor Distinto:
- Monitora os valores atual e anterior
- Detecta automaticamente se uma mudança é significativa com base em seus critérios
Comparação Profunda:
- Permite verificações de igualdade em nível profundo para objetos complexos
Comparação Personalizada:
- Suporta funções personalizadas para definir o que constitui uma mudança "distinta"
Debounced:
- Reduz atualizações desnecessárias quando as mudanças ocorrem com muita frequência

Benefícios

API idêntica ao useState: Fácil de integrar em componentes existentes.
Desempenho Otimizado: Evita refetching ou recálculos desnecessários quando o valor não mudou significativamente. UX Aprimorada: Previne atualizações excessivamente reativas da UI, resultando em interações mais suaves.
Lógica Simplificada: Elimina verificações manuais de igualdade ou duplicação no gerenciamento de estado.

Os hooks do React Edge foram desenhados para trabalhar em harmonia, proporcionando uma experiência de desenvolvimento fluida e tipada. A combinação deles permite criar interfaces complexas e reativas com muito menos código.

A CLI do React Edge: Potência na Ponta dos Dedos

A CLI do React Edge foi projetada para simplificar a vida dos desenvolvedores, reunindo ferramentas essenciais em uma interface única e intuitiva. Seja você iniciante ou experiente, a CLI garante que você possa configurar, desenvolver, testar e implantar projetos com eficiência e sem complicações.

Principais Recursos

Comandos Modulares e Flexíveis:

build: Constrói tanto o app quanto o worker, com opções para especificar ambientes e modos de desenvolvimento ou produção.
dev: Inicia servidores de desenvolvimento locais ou remotos, permitindo trabalhar separadamente no app ou no worker.
deploy: Realiza deploys rápidos e eficientes utilizando o poder combinado do Cloudflare Workers e do Cloudflare R2, garantindo performance e escalabilidade na infraestrutura edge.
logs: Monitora logs do worker diretamente no terminal.
lint: Automatiza a execução do Prettier e do ESLint, com suporte a correções automáticas.
test: Executa testes com cobertura opcional usando Vitest.
type-check: Valida a tipagem TypeScript no projeto.

Casos de Uso em Produção

Tenho o orgulho de compartilhar que a primeira aplicação em produção utilizando o React Edge já está funcionando! Trata-se de uma imobiliária brasileira, a Lopes Imóveis, que já está aproveitando toda a performance e flexibilidade do framework.

No site da imobiliária, os imóveis são carregados em cache para otimizar a busca e oferecer uma experiência mais fluida para os usuários. Por se tratar de um site extremamente dinâmico, o cache das rotas utiliza um TTL de apenas 10 segundos, combinado com a estratégia stale-while-revalidate. Isso garante que o site entregue dados atualizados com uma performance excepcional, mesmo durante revalidações em segundo plano.

Além disso, as recomendações de imóveis similares são calculadas de maneira eficiente e eventual em background, e salvas diretamente no cache da Cloudflare, utilizando o sistema de cache integrado ao RPC. Essa abordagem reduz o tempo de resposta em requisições subsequentes e torna a query das recomendações quase instantânea. Além de que todas as imagens estão armazenadas no Cloudflare R2, oferecendo armazenamento escalável e distribuído sem depender de provedores externos.

E logo teremos também o lançamento de um projeto gigantesco de marketing automatizado para a Easy Auth, mostrando ainda mais o potencial dessa tecnologia.

Conclusão

E assim, caros leitores, chegamos ao fim desta aventura pelo universo do React Edge! Sei que ainda há um mar de coisas incríveis para explorar, como as autenticações mais simples como Basic e Bearer, e outros segredinhos que fazem o dia a dia de um dev muito mais feliz. Mas calma lá! A ideia é trazer mais artigos detalhados no futuro para mergulhar de cabeça em cada uma dessas funcionalidades.

E, spoiler: logo o React Edge será open source e devidamente documentado! Conciliar desenvolvimento, trabalho, escrever e um pouquinho de vida social não é fácil, mas a empolgação de ver essa maravilha em ação, especialmente com a velocidade absurda proporcionada pela infraestrutura da Cloudflare, é o combustível que me move. Então, segura a ansiedade, porque o melhor ainda está por vir! 🚀

Enquanto isso, se você quiser começar a explorar e testar agora mesmo, o pacote já está disponível no NPM: React Edge no NPM..

Meu e-mail é feliperohdee@gmail.com, e estou sempre aberto a feedbacks, esta é só inicio desta jornada, sugestões e críticas construtivas. Se você gostou do que leu, compartilhe com seus amigos e colegas, e fique de olho nas novidades que estão por vir. Obrigado por me acompanhar até aqui, e até a próxima! 🚀🚀🚀

From Next.js to React Edge with Cloudflare Workers: A Story of Liberation

Felipe Rohde — Mon, 18 Nov 2024 18:56:35 +0000

Quick Index

The Final Straw
The Alternative with Cloudflare 😍
React Edge: The React Framework Born from Every Developer’s Pain (or Almost)
- The Magic of Typed RPC
- The Power of useFetch: Where the Magic Happens
Beyond useFetch: The Complete Arsenal
- RPC: The Art of Client-Server Communication
- An i18n System That Makes Sense
- JWT Authentication That "Just Works"
- The Shared Store
- Elegant Routing
- Distributed Cache with Edge Cache
Link: The Component That Thinks Ahead
app.useContext: The Portal to the Edge
app.useUrlState: State Synced with the URL
app.useStorageState: Persistent State
app.useDebounce: Frequency Control
app.useDistinct: State Without Duplicates
The React Edge CLI: Power at Your Fingertips
Conclusion

The Final Straw

It all started with a Vercel invoice. No, actually, it started way earlier—with small frustrations piling up. The need to pay for basic features like DDoS protection, more detailed logs, or even a decent firewall, build queues, etc. The feeling of being trapped in an increasingly expensive vendor lock-in.

"And worst of all: our precious SEO headers simply stopped rendering on the server in an application using the pages router. A true headache for any developer! 😭"

But what truly made me rethink everything was the direction Next.js was heading. The introduction of use client, use server—directives that, in theory, should simplify development but, in practice, added another layer of complexity to manage. It was like going back to the PHP days, marking files with directives to dictate where they should run.

And it doesn’t stop there. The App Router—an interesting idea but implemented in a way that created an almost entirely new framework within Next.js. Suddenly, there were two completely different ways to do the same thing—the 'old' and the 'new'—with subtly different behaviors and hidden pitfalls.

The Alternative with Cloudflare 😍

That’s when it hit me: why not leverage the incredible infrastructure of Cloudflare with Workers running on the edge, R2 for storage, KV for distributed data... Along with, of course, the amazing DDoS protection, global CDN, firewall, page rules and routing, and everything else Cloudflare has to offer.

And the best part: a fair pricing model where you pay for what you use, with no surprises.

This is how React Edge was born. A framework that doesn’t aim to reinvent the wheel but instead delivers a truly simple and modern development experience.

React Edge: The React Framework Born from Every Developer’s Pain (or Almost)

When I started developing React Edge, I had a clear goal: to create a framework that made sense. No more wrestling with confusing directives, no more paying exorbitant fees for basic features, and most importantly, no more dealing with artificial complexity caused by client/server separation. I wanted speed—a framework that delivers performance without sacrificing simplicity. Leveraging my knowledge of React’s API and years of experience as a JavaScript and Golang developer, I knew exactly how to handle streams and multiplexing to optimize rendering and data management.

Cloudflare Workers, with its powerful infrastructure and global presence, provided the perfect environment to explore these possibilities. I wanted something truly hybrid, and this combination of tools and experience gave life to React Edge: a framework that solves real-world problems with modern and efficient solutions.

React Edge introduces a revolutionary approach to React development. Imagine writing a class on the server and calling it directly from the client, with full type safety and zero configuration. Imagine a distributed caching system that "just works," allowing invalidation by tags or prefixes. Imagine sharing state seamlessly and securely between server and client. Add simplified authentication, an efficient internationalization system, CLI, and more.

Its RPC communication feels almost magical—you write methods in a class and call them from the client as if they were local. The intelligent multiplexing system ensures that even if multiple components make the same call, only one request is sent to the server. Ephemeral caching avoids unnecessary repeated requests, and it all works seamlessly on both the server and the client.

One of the most powerful features is the app.useFetch hook, which unifies the data-fetching experience. On the server, it preloads data during SSR; on the client, it automatically hydrates with those data and supports on-demand updates. With support for automatic polling and dependency-based reactivity, creating dynamic interfaces has never been easier.

But that’s not all. The framework offers a powerful routing system (inspired by the fantastic Hono), integrated asset management with Cloudflare R2, and an elegant way to handle errors via the HttpError class. Middlewares can easily send data to the client through a shared store, and everything is automatically obfuscated for security.

The most impressive part? Almost all of the framework’s code is hybrid. There isn’t a “client” version and a “server” version—the same code works in both environments, adapting automatically to the context. The client receives only what it needs, making the final bundle extremely optimized.

And the icing on the cake: all of this runs on the Cloudflare Workers edge infrastructure, delivering exceptional performance at a fair cost. No surprise invoices, no basic features locked behind expensive enterprise plans—just a solid framework that lets you focus on what truly matters: building amazing applications. Additionally, React Edge leverages Cloudflare’s ecosystem, including Queues, Durable Objects, KV Storage, and more, providing a robust and scalable foundation for your applications.

Vite was used as the base for the development environment, testing, and build process. With its impressive speed and modern architecture, Vite enables an agile and efficient workflow. It not only accelerates development but also optimizes the build process, ensuring fast and accurate compilation. Without a doubt, Vite was the perfect choice for React Edge.

Rethinking React Development for the Edge Computing Era

Have you ever wondered what it would be like to develop React applications without worrying about the client/server barrier? Without memorizing dozens of directives like use client or use server? Better yet: what if you could call server functions as if they were local, with full typing and zero configuration?

With React Edge, you no longer need to:

Create separate API routes
Manually manage loading/error state
Implement debounce yourself
Worry about serialization/deserialization
Deal with CORS
Manage typing between client/server
Handle authentication rules manually
Struggle with internationalization setup

And the best part: all this works seamlessly on both the server and client without marking anything as use client or use server. The framework automatically knows what to do based on the context. Shall we dive in?

The Magic of Typed RPC

Imagine being able to do this:

// On the server
class UserAPI extends Rpc {
  async searchUsers(query: string, filters: UserFilters) {
    // Validation with Zod
    const validated = searchSchema.parse({ query, filters });
    return this.db.users.search(validated);
  }
}

// On the client
const UserSearch = () => {
  const { rpc } = app.useContext<App.Context>();

  // TypeScript knows exactly what searchUsers accepts and returns!
  const { data, loading, error, fetch: retry } = app.useFetch(
    async (ctx) => ctx.rpc.searchUsers('John', { age: '>18' })
  );
};

Compare this with Next.js/Vercel:

// pages/api/search.ts
export default async handler = (req, res) => {
  // Configure CORS
  // Validate request
  // Handle errors
  // Serialize response
  // ...100 lines later...
}

// app/search/page.tsx
'use client';
import { useEffect, useState } from 'react';

export default const SearchPage = () => {
  const [search, setSearch] = useState('');
  const [filters, setFilters] = useState({});
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    let timeout;
    const doSearch = async () => {
      setLoading(true);
      try {
        const res = await fetch('/api/search?' + new URLSearchParams({
          q: search,
          ...filters
        }));
        if (!res.ok) throw new Error('Search failed');
        setData(await res.json());
      } catch (err) {
        console.error(err);
      } finally {
        setLoading(false);
      }
    };

    timeout = setTimeout(doSearch, 300);
    return () => clearTimeout(timeout);
  }, [search, filters]);

  // ... rest of the component
}

The Power of `useFetch`: Where the Magic Happens

Rethinking Data Fetching

Forget everything you know about data fetching in React. The app.useFetch hook from React Edge introduces a completely new and powerful approach. Imagine a hook that:

Preloads data on the server during SSR.
Automatically hydrates data on the client without flicker.
Maintains full typing between client and server.
Supports reactivity with intelligent debounce.
Automatically multiplexes identical calls.
Enables programmatic updates and polling.

Let’s see it in action:

// First, define your API on the server
class PropertiesAPI extends Rpc {
  async searchProperties(filters: PropertyFilters) {
    const results = await this.db.properties.search(filters);
    // Automatic caching for 5 minutes
    return this.createResponse(results, {
      cache: { ttl: 300, tags: ['properties'] }
    });
  }

  async getPropertyDetails(ids: string[]) {
    return Promise.all(
      ids.map(id => this.db.properties.findById(id))
    );
  }
}

// Now, on the client, the magic happens
const PropertySearch = () => {
  const [filters, setFilters] = useState<PropertyFilters>({
    price: { min: 100000, max: 500000 },
    bedrooms: 2
  });

  // Reactive search with intelligent debounce
  const {
    data: searchResults,
    loading: searchLoading,
    error: searchError
  } = app.useFetch(
    async (ctx) => ctx.rpc.searchProperties(filters),
    {
      // Re-fetch when filters change
      deps: [filters],
      // Wait 300ms of "silence" before fetching
      depsDebounce: {
        filters: 300
      }
    }
  );

  // Fetch property details for the found results
  const {
    data: propertyDetails,
    loading: detailsLoading,
    fetch: refreshDetails
  } = app.useFetch(
    async (ctx) => {
      if (!searchResults?.length) return null;

      // This looks like multiple calls, but...
      return ctx.rpc.batch([
        // Everything is multiplexed into a single request!
        ...searchResults.map(result =>
          ctx.rpc.getPropertyDetails(result.id)
        )
      ]);
    },
    {
      // Refresh when searchResults change
      deps: [searchResults]
    }
  );

  // A beautiful and responsive interface
  return (
    <div>
      <FiltersPanel
        value={filters}
        onChange={setFilters}
        disabled={searchLoading}
      />

      {searchError && (
        <Alert status='error'>
          Search error: {searchError.message}
        </Alert>
      )}

      <PropertyGrid
        items={propertyDetails || []}
        loading={detailsLoading}
        onRefresh={() => refreshDetails()}
      />
    </div>
  );
};

The Magic of Multiplexing

The example above hides a powerful feature: intelligent multiplexing. When you use ctx.rpc.batch, React Edge not only groups calls—it also deduplicates identical calls automatically:

const PropertyListingPage = () => {
  const { data } = app.useFetch(async (ctx) => {
    // Even if you make 100 identical calls...
    return ctx.rpc.batch([
      ctx.rpc.getProperty('123'),
      ctx.rpc.getProperty('123'), // same call
      ctx.rpc.getProperty('456'),
      ctx.rpc.getProperty('456'), // same call
    ]);
  });

  // Behind the scenes:
  // 1. The batch groups all calls into ONE single HTTP request.
  // 2. Identical calls are deduplicated automatically.
  // 3. Results are distributed correctly to each position in the array.
  // 4. Typing is maintained for each individual result!

  // Actual RPC calls:
  // 1. getProperty('123')
  // 2. getProperty('456')
  // Results are distributed correctly to all callers!
};

SSR + Perfect Hydration

One of the most impressive parts is how useFetch handles SSR:

const ProductPage = ({ productId }: Props) => {
  const { data, loaded, loading, error } = app.useFetch(
    async (ctx) => ctx.rpc.getProduct(productId),
    {
      // Fine-grained control over when to fetch
      shouldFetch: ({ worker, loaded }) => {
        // On the worker (SSR): always fetch
        if (worker) return true;
        // On the client: fetch only if no data is loaded
        return !loaded;
      }
    }
  );

  // On the server:
  // 1. `useFetch` makes the RPC call.
  // 2. Data is serialized and sent to the client.
  // 3. Component renders with the data.

  // On the client:
  // 1. Component hydrates with server data.
  // 2. No new call is made (shouldFetch returns false).
  // 3. If necessary, you can re-fetch with `data.fetch()`.

  return (
    <Suspense fallback={<ProductSkeleton />}>
      <ProductView
        product={data}
        loading={loading}
        error={error}
      />
    </Suspense>
  );
};

Beyond useFetch: The Complete Arsenal

RPC: The Art of Client-Server Communication

Security and Encapsulation

The RPC system in React Edge is designed with security and encapsulation in mind. Not everything in an RPC class is automatically exposed to the client:

class PaymentsAPI extends Rpc {
  // Properties are never exposed
  private stripe = new Stripe(process.env.STRIPE_KEY);

  // Methods starting with $ are private
  private async $validateCard(card: CardInfo) {
    return await this.stripe.cards.validate(card);
  }

  // Methods starting with _ are also private
  private async _processPayment(amount: number) {
    return await this.stripe.charges.create({ amount });
  }

  // This method is public and accessible via RPC
  async createPayment(orderData: OrderData) {
    // Internal validation using a private method
    const validCard = await this.$validateCard(orderData.card);
    if (!validCard) {
      throw new HttpError(400, 'Invalid card');
    }

    // Processing using another private method
    const payment = await this._processPayment(orderData.amount);
    return payment;
  }
}

// On the client:
const PaymentForm = () => {
  const { rpc } = app.useContext<App.Context>();

  // ✅ This works
  const handleSubmit = () => rpc.createPayment(data);

  // ❌ These do not work - private methods are not exposed
  const invalid1 = () => rpc.$validateCard(data);
  const invalid2 = () => rpc._processPayment(100);

  // ❌ This also does not work - properties are not exposed
  const invalid3 = () => rpc.stripe;
};

RPC API Hierarchies

One of the most powerful features of RPC is the ability to organize APIs into hierarchies:

// Nested APIs for better organization
class UsersAPI extends Rpc {
  // Subclass to manage preferences
  preferences = new UserPreferencesAPI();
  // Subclass to manage notifications
  notifications = new UserNotificationsAPI();

  async getProfile(id: string) {
    return this.db.users.findById(id);
  }
}

class UserPreferencesAPI extends Rpc {
  async getTheme(userId: string) {
    return this.db.preferences.getTheme(userId);
  }

  async setTheme(userId: string, theme: Theme) {
    return this.db.preferences.setTheme(userId, theme);
  }
}

class UserNotificationsAPI extends Rpc {
  // Private methods remain private
  private async $sendPush(userId: string, message: string) {
    await this.pushService.send(userId, message);
  }

  async getSettings(userId: string) {
    return this.db.notifications.getSettings(userId);
  }

  async notify(userId: string, notification: Notification) {
    const settings = await this.getSettings(userId);
    if (settings.pushEnabled) {
      await this.$sendPush(userId, notification.message);
    }
  }
}

// On the client:
const UserProfile = () => {
  const { rpc } = app.useContext<App.Context>();

  const { data: profile } = app.useFetch(
    async (ctx) => {
      // Nested calls are fully typed
      const [user, theme, notificationSettings] = await ctx.rpc.batch([
        // Method from the main class
        ctx.rpc.getProfile('123'),
        // Method from the preferences subclass
        ctx.rpc.preferences.getTheme('123'),
        // Method from the notifications subclass
        ctx.rpc.notifications.getSettings('123')
      ]);

      return { user, theme, notificationSettings };
    }
  );

  // ❌ Private methods remain inaccessible
  const invalid = () => rpc.notifications.$sendPush('123', 'hello');
};

Benefits of Hierarchies

Organizing APIs into hierarchies provides several benefits:

Logical Organization: Group related functionalities intuitively.
Natural Namespacing: Avoid name conflicts with clear paths (e.g., users.preferences.getTheme).
Encapsulation: Keep helper methods private at each level.
Maintainability: Each subclass can be maintained and tested independently.
Full Typing: TypeScript understands the entire hierarchy.

The RPC system in React Edge makes client-server communication so natural that you almost forget you’re making remote calls. With the ability to organize APIs into hierarchies, you can build complex structures while keeping your code clean and secure.

A System of i18n That Makes Sense

React Edge introduces an elegant and flexible internationalization system that supports variable interpolation and complex formatting without relying on heavyweight libraries.

// translations/fr.ts
export default {
  'Good Morning, {name}!': 'Bonjour, {name}!',
};

Usage in the code:

const WelcomeMessage = () => {
  const userName = 'John';

  return (
    <div>
      {/* Output: Good Morning, John! */}
      <h1>{__('Good Morning, {name}!', { name: userName })}</h1>
    </div>
  );
};

Zero Configuration

React Edge automatically detects and loads your translations. It even allows saving user preferences in cookies effortlessly. But, of course, you’d expect this, right?

// worker.ts
const handler = {
  fetch: async (request: Request, env: types.Worker.Env, context: ExecutionContext) => {
    const url = new URL(request.url);

    const lang = (() => {
      const lang =
        url.searchParams.get('lang') || worker.cookies.get(request.headers, 'lang') || request.headers.get('accept-language') || '';

      if (!lang || !i18n[lang]) {
        return 'en-us';
      }

      return lang;
    })();

    const workerApp = new AppWorkerEntry({
      i18n: {
        en: await import('./translations/en'),
        pt: await import('./translations/pt'),
        es: await import('./translations/es')
      }
    });

    const res = await workerApp.fetch();

    if (url.searchParams.has('lang')) {
      return new Response(res.body, {
        headers: worker.cookies.set(res.headers, 'lang', lang)
      });
    }

    return res;
  }
};

JWT Authentication That "Just Works"

Authentication has always been a pain point in web applications. Managing JWT tokens, secure cookies, and revalidation often requires a lot of boilerplate code. React Edge completely changes this.

Here’s how simple it is to implement a full authentication system:

class SessionAPI extends Rpc {
  private auth = new AuthJwt({
    // Cookie is automatically managed
    cookie: 'token',
    // Payload is automatically encrypted
    encrypt: true,
    // Automatic expiration
    expires: { days: 1 },
    secret: process.env.JWT_SECRET,
  });

  async signin(credentials: { email: string; password: string }) {
    // Validation with Zod
    const validated = loginSchema.parse(credentials);

    // Signs the token and sets the headers automatically
    const { headers } = await this.auth.sign(validated);

    // Returns a response with configured cookies
    return this.createResponse(
      { email: validated.email },
      { headers }
    );
  }

  async getSession(revalidate = false) {
    // Automatic token validation and revalidation
    const { headers, payload } = await this.auth.authenticate(
      this.request.headers,
      revalidate
    );

    return this.createResponse(payload, { headers });
  }

  async signout() {
    // Automatically clears cookies
    const { headers } = await this.auth.destroy();
    return this.createResponse(null, { headers });
  }
}

Client Usage: Zero Configuration

const LoginForm = () => {
  const { rpc } = app.useContext<App.Context>();

  const login = async (values) => {
    const session = await rpc.signin(values);
    // Done! Cookies are automatically set
  };

  return <Form onSubmit={login}>...</Form>;
};

const NavBar = () => {
  const { rpc } = app.useContext<App.Context>();

  const logout = async () => {
    await rpc.signout();
    // Cookies are automatically cleared
  };

  return <button onClick={logout}>Log Out</button>;
};

Why Is This Revolutionary?

Zero Boilerplate
- No manual cookie management
- No need for interceptors
- No manual refresh tokens
Security by Default
- Tokens are automatically encrypted
- Cookies are secure and httpOnly
- Automatic revalidation
Full Typing
- JWT payload is typed
- Integrated Zod validation
- Typed authentication errors
Seamless Integration

// Middleware to protect routes
const authMiddleware: App.Middleware = async (ctx) => {
  const session = await ctx.rpc.session.getSession();

  if (!session) {
    throw new HttpError(401, 'Unauthorized');
  }

  // Makes the session available to components
  ctx.store.set('session', session, 'public');
};

// Usage in routes
const router: App.Router = {
  routes: [
    routerBuilder.routeGroup({
      path: '/dashboard',
      middlewares: [authMiddleware],
      routes: [/*...*/],
    }),
  ],
};

The Shared Store

One of the most powerful features of React Edge is its ability to securely share state between the worker and the client. Here's how it works:

Example of Middleware and Store Usage

// middleware/auth.ts
const authMiddleware: App.Middleware = async (ctx) => {
  const token = ctx.request.headers.get('authorization');

  if (!token) {
    throw new HttpError(401, 'Unauthorized');
  }

  const user = await validateToken(token);

  // Public data - automatically shared with the client
  ctx.store.set(
    'user',
    {
      id: user.id,
      name: user.name,
      role: user.role,
    },
    'public'
  );

  // Private data - remains accessible only within the worker
  ctx.store.set('userSecret', user.secret);
};

// components/Header.tsx
const Header = () => {
  // Acesso transparente aos dados do store
  const { store } = app.useContext();
  const user = store.get('user');

  return (
    <header>
      <h1>Bem vindo, {user.name}!</h1>
      {user.role === 'admin' && (
        <AdminPanel />
      )}
    </header>
  );
};

How It Works

Public Data: Data marked as public is securely shared with the client, making it easily accessible for components.
Private Data: Sensitive data remains within the worker’s environment and is never exposed to the client.
Integration with Middleware: Middleware can populate the store with both public and private data, ensuring a seamless flow of information between server-side logic and client-side rendering.

Benefits

Security: Separate public and private data scopes ensure sensitive information stays protected.
Convenience: Transparent access to store data simplifies state management across worker and client.
Flexibility: The store is easily integrated with middleware, allowing dynamic state updates based on request handling.

Elegant Routing

The routing system of React Edge is inspired by Hono, but with enhanced features for SSR:

const router: App.Router = {
  routes: [
    routerBuilder.routeGroup({
      path: '/dashboard',
      // Middlewares applied to all routes in the group
      middlewares: [authMiddleware, dashboardMiddleware],
      routes: [
        routerBuilder.route({
          path: '/',
          handler: {
            page: {
              value: DashboardPage,
              // Specific headers for this route
              headers: new Headers({
                'Cache-Control': 'private, max-age=0'
              })
            }
          }
        }),
        routerBuilder.route({
          path: '/api/stats',
          handler: {
            // Routes can return direct responses
            response: async (ctx) => {
              const stats = await ctx.rpc.stats.getDashboardStats();
              return {
                value: Response.json(stats),
                // Cache for 5 minutes
                cache: { ttl: 300 }
              };
            }
          }
        })
      ]
    })
  ]
};

Key Features

Grouped Routes: Logical grouping of related routes under a shared path and middleware.
Flexible Handlers: Define handlers that return pages or direct API responses.
Per-Route Headers: Customize HTTP headers for individual routes.
Built-in Caching: Simplify caching strategies with ttl and tags.

Benefits

Consistency: By grouping related routes, you ensure consistent middleware application and code organization.
Scalability: The system supports nested and modular routing for large-scale applications.
Performance: Native support for caching ensures optimal response times without manual configurations.

Distributed Cache with Edge Cache

React Edge includes a powerful caching system that works seamlessly for both JSON data and entire pages. This caching system supports intelligent tagging and prefix-based invalidation, making it suitable for a wide range of scenarios.

Example: Caching API Responses with Tags

class ProductsAPI extends Rpc {
  async getProducts(category: string) {
    const products = await this.db.products.findByCategory(category);

    return this.createResponse(products, {
      cache: {
        ttl: 3600, // 1 hour
        tags: [`category:${category}`, 'products'],
      },
    });
  }

  async updateProduct(id: string, data: ProductData) {
    await this.db.products.update(id, data);

    // Invalidate specific product cache and its category
    await this.cache.deleteBy({
      tags: [`product:${id}`, `category:${data.category}`],
    });
  }

  async searchProducts(query: string) {
    const results = await this.db.products.search(query);

    // Cache with a prefix for easy invalidation
    return this.createResponse(results, {
      cache: {
        ttl: 300, // 5 minutes
        tags: [`search:${query}`],
      },
    });
  }
}

// Global cache invalidation
await cache.deleteBy({
  // Invalidate all search results
  keyPrefix: 'search:',
  // And all products in a specific category
  tags: ['category:electronics'],
});

Key Features

Tag-Based Invalidation: Cache entries can be grouped using tags, allowing for easy and selective invalidation when data changes.
Prefix Matching: Invalidate multiple cache entries using a common prefix, ideal for scenarios like search queries or hierarchical data.
Time-to-Live (TTL): Set expiration times for cache entries to ensure data freshness while maintaining high performance.

Benefits

Improved Performance: Reduce load on APIs by serving cached responses for frequently accessed data.
Scalability: Efficiently handle large-scale datasets and high traffic with a distributed caching system.
Flexibility: Fine-grained control over caching, enabling developers to optimize performance without sacrificing data accuracy.

Link: The Component That Thinks Ahead

The Link component is an intelligent and performance-oriented solution for preloading client-side resources, ensuring a smoother and faster navigation experience for users. Its prefetching functionality is triggered when the user hovers over the link, taking advantage of idle moments to request destination data in advance.

How It Works

Conditional Prefetching: The prefetch attribute (enabled by default) controls whether the preloading is executed.
Intelligent Cache: A Set is used to store already prefetched links, avoiding redundant fetch calls.
Mouse Enter Event: When the user hovers over the link, the handleMouseEnter function checks if preloading is necessary and, if so, starts a fetch request for the destination.
Error Resilience: Any failure during the request is suppressed, ensuring the component's behavior is unaffected by temporary network issues.

Example Usage

<app.Link href="/about" prefetch>
  About Us
</app.Link>

When the user hovers over the “About Us” link, the component will start preloading the data for the /about page, ensuring an almost instant transition. Genius idea, isn’t it? Inspired by the react.dev documentation.

app.useContext: The Portal to the Edge

The app.useContext hook is a cornerstone of React Edge, granting seamless access to the worker's entire context. It provides a powerful interface for managing routing, state, RPC calls, and more.

Example: Using app.useContext in a Dashboard

const DashboardPage = () => {
  const {
    // Current route parameters
    pathParams,
    // Parsed query parameters
    searchParams,
    // Matched route
    path,
    // Original route (with parameters)
    rawPath,
    // RPC proxy
    rpc,
    // Shared store
    store,
    // Full URL
    url,
  } = app.useContext<App.Context>();

  // Fully typed RPC call
  const { data } = app.useFetch(
    async (ctx) => ctx.rpc.getDashboardStats()
  );

  // Accessing shared store data
  const user = store.get('user');

  return (
    <div>
      <h1>Welcome to your dashboard, {user.name}</h1>
      <p>Currently viewing: {path}</p>
    </div>
  );
};

Key Features of app.useContext

Route Management: Gain access to the matched route, its parameters, and query strings effortlessly.
RPC Integration: Make typed and secure RPC calls directly from the client with no additional configuration.
Shared Store Access: Retrieve or set values in the shared worker-client state with complete control over visibility (public/private).
Universal URL Access: Easily access the full URL of the current request for dynamic rendering and interactions.

Why It’s Powerful

The app.useContext hook bridges the gap between the worker and the client. It allows you to build features that rely on shared state, secure data fetching, and contextual rendering without boilerplate. This simplifies complex applications, making them easier to maintain and faster to develop.

app.useUrlState: State Synced with the URL

The app.useUrlState hook keeps your application state in sync with the URL query parameters, offering fine-grained control over what is included in the URL, how the state is serialized, and when it updates.

const ProductsPage = () => {
  // State synced with URL automatically
  const [filters, setFilters] = app.useUrlState({
      category: 'all',
      minPrice: 0,
      maxPrice: 1000,
      other: {
          foo: 'bar',
          baz: 'qux'
      }
    }, {
        debounce: 500,              // Debounce URL updates by 500ms
        kebabCase: true,            // Converts keys to kebab-case for cleaner URLs
        omitKeys: ['filter.locations'], // Exclude specific keys from the URL
        omitValues: [],             // Exclude specific values from the URL
        pickKeys: [], // Include only specific keys in the URL
        prefix: '',                 // Add an optional prefix to query keys
        url: ctx.url                // Use the current URL from the context (works server side)
    });

  const { data } = app.useFetch(
    async (ctx) => ctx.rpc.products.search(filters),
    {
      // Refetch quando filters mudar
      deps: [filters]
    }
  );

  return (
    <div>
      <FiltersPanel
        value={filters}
        onChange={(newFilters) => {
          // URL é atualizada automaticamente
          setFilters(newFilters);
        }}
      />
      <ProductGrid data={data} />
    </div>
  );
};

Parameters

Initial State
- An object defining the default structure and values for your state.
Options:
- debounce: Controls how quickly the URL is updated after state changes. Useful for preventing excessive updates.
- kebabCase: Converts state keys to kebab-case when serializing to the URL (e.g., filter.locations → filter-locations).
- omitKeys: Specifies keys to exclude from the URL. For example, sensitive data or large objects can be omitted.
- omitValues: Values that, when present, will exclude the associated key from the URL.
- pickKeys: Limits the serialized state to only include specified keys.
- prefix: Adds a prefix to all query parameters for namespacing.
- url: The base URL to sync with, typically derived from the app context.

Benefits

Identical useState API: Easy integration with existing components.
SEO-Friendly: Ensures state-dependent views are reflected in sharable and bookmarkable URLs.
Debounced Updates: Prevents excessive query updates for rapidly changing inputs, like sliders or text boxes.
Clean URLs: Options like kebabCase and omitKeys keep query strings readable and relevant.
State Hydration: Automatically initializes state from the URL on component mount, making deep linking seamless.
Works Everywhere: Supports server-side rendering and client-side navigation, ensuring consistent state across the application.

Practical Applications

Filters for Property Listings: Sync user-applied filters like listingTypes and map bounds to the URL for sharable searches.
Dynamic Views: Ensure map zoom, center points, or other view settings persist across page refreshes or links.
User Preferences: Save user-selected settings in the URL for easy sharing or bookmarking.

app.useStorageState: Persistent State

The app.useStorageState hook allows you to persist state in the browser using localStorage or sessionStorage, with full TypeScript support.

type RecentSearch = {
  term: string;
  date: string;
  category: string;
}

type SearchState = {
  recentSearches: RecentSearch[];
  favorites: string[];
  lastSearch?: string;
}

const RecentSearches = () => {
  // Initialize state with typing and default values
  const [searchState, setSearchState] = app.useStorageState<SearchState>(
    // Unique key for storage
    'user-searches',
    // Initial state
    {
      recentSearches: [],
      favorites: [],
      lastSearch: undefined
    },
    // Configuration options
    {
      // Delays saving to storage by 500ms to optimize performance
      debounce: 500,

      // Sets the storage type:
      // 'local' - persists even after closing the browser
      // 'session' - persists only during the session
      storage: 'local',

      // Exclude these keys when saving to storage
      omitKeys: ['lastSearch'],

      // Save only these specific keys
      pickKeys: ['recentSearches', 'favorites']
    }
  );

  return (
    <div className="recent-searches">
      <h3>Recent Searches</h3>

      {/* List recent searches */}
      <ul>
        {searchState.recentSearches.map((search, index) => (
          <li key={index}>
            <span>{search.term}</span>
            <small>{search.date}</small>

            {/* Button to favorite search */}
            <button
              onClick={() => {
                setSearchState({
                  ...searchState,
                  favorites: [...searchState.favorites, search.term]
                })
              }}
            >
              ⭐
            </button>
          </li>
        ))}
      </ul>

      {/* Button to clear history */}
      <button
        onClick={() => {
          setSearchState({
            ...searchState,
            recentSearches: []
          })
        }}
      >
        Clear History
      </button>
    </div>
  );
};

Persistence Options

debounce: Controls the frequency of saves to storage.
storage: Choose between localStorage and sessionStorage.
omitKeys/pickKeys: Fine-grained control over which data is persisted.

Performance

Optimized updates with debounce.
Automatic serialization/deserialization.
In-memory caching.

Common Use Cases

Search history
Favorites list
User preferences
Filter state
Temporary shopping cart
Draft forms

app.useDebounce: Frequency Control

Debounce reactive values effortlessly:

const SearchInput = () => {
  const [input, setInput] = useState('');

  // Debounced value updates only after 300ms of 'silence'
  const debouncedValue = app.useDebounce(input, 300);

  const { data } = app.useFetch(
    async (ctx) => ctx.rpc.search(debouncedValue),
    {
      // Fetch occurs only when the debounced value changes
      deps: [debouncedValue]
    }
  );

  return (
    <div>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        placeholder='Search...'
      />
      <SearchResults data={data} />
    </div>
  );
};

app.useDistinct: State Without Duplicates

Keep arrays with unique values while maintaining type safety.

The app.useDistinct hook specializes in detecting when a value has truly changed, with support for deep comparison and debounce:

const SearchResults = () => {
  const [search, setSearch] = useState('');

  // Detect distinct changes in the search value
  const {
    value: currentSearch,   // Current value
    prevValue: lastSearch,  // Previous value
    distinct: hasChanged    // Indicates if a distinct change occurred
  } = app.useDistinct(search, {
    // Debounce by 300ms
    debounce: 300,
    // Enable deep comparison
    deep: true,
    // Custom comparison function
    compare: (a, b) => a?.toLowerCase() === b?.toLowerCase()
  });

  // Fetch only when the search value has distinctly changed
  const { data } = app.useFetch(
    async (ctx) => ctx.rpc.search(currentSearch),
    {
      deps: [currentSearch],
      // Execute fetch only if there's a distinct change
      shouldFetch: () => hasChanged
    }
  );

  return (
    <div>
      <input
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        placeholder="Search..."
      />

      {hasChanged && (
        <small>
          Search updated from '{lastSearch}' to '{currentSearch}'
        </small>
      )}

      <SearchResults data={data} />
    </div>
  );
};

Key Features

Distinct Value Detection:
- Tracks the current and previous values.
- Automatically detects if a change is meaningful based on your criteria.
Deep Comparison:
- Enables value equality checks at a deep level for complex objects.
Custom Comparison:
- Supports custom functions to define what constitutes a “distinct” change.
Debounced:
- Reduces unnecessary updates when changes occur too frequently.

Benefits

Identical useState API: Easy integration with existing components.
Optimized Performance: Avoids unnecessary re-fetching or re-computation when the value hasn’t meaningfully changed.
Enhanced UX: Prevents overreactive UI updates, leading to smoother interactions.
Simplified Logic: Eliminates manual checks for equality or duplication in state management.

The hooks in React Edge are designed to work in harmony, providing a fluid and strongly typed development experience. Their combination allows for creating complex and reactive interfaces with much less code.

The React Edge CLI: Power at Your Fingertips

The CLI for React Edge was designed to simplify developers' lives by gathering essential tools into a single, intuitive interface. Whether you're a beginner or an experienced developer, the CLI ensures you can configure, develop, test, and deploy projects efficiently and effortlessly.

Key Features

Modular and Flexible Commands:

build: Builds both the app and the worker, with options to specify environments and modes (development or production).
dev: Starts local or remote development servers, allowing separate work on the app or worker.
deploy: Enables fast and efficient deployments leveraging the combined power of Cloudflare Workers and Cloudflare R2, ensuring performance and scalability in edge infrastructure.
logs: Monitors worker logs directly in the terminal.
lint: Automates Prettier and ESLint execution, with support for auto-fixes.
test: Runs tests with optional coverage using Vitest.
type-check: Validates TypeScript typing across the project.

Real-World Use Cases

I’m proud to share that the first production application using React Edge is already live! It's a Brazilian real estate company, Lopes Imóveis, which is already reaping the benefits of the framework's performance and flexibility.

On their website, properties are loaded into cache to optimize search and provide a smoother user experience. Since it's a highly dynamic site, route caching uses a TTL of just 10 seconds, combined with the stale-while-revalidate strategy. This ensures the site delivers updated data with exceptional performance, even during background revalidations.

Additionally, recommendations for similar properties are calculated efficiently and asynchronously in the background, then saved directly to Cloudflare's cache using the integrated RPC caching system. This approach reduces response times for subsequent requests and makes querying recommendations nearly instantaneous. All images are stored on Cloudflare R2, offering scalable and distributed storage without relying on external providers.

Soon, we’ll also launch a massive automated marketing project for Easy Auth, showcasing the potential of this technology even further.

Conclusion

And so, dear readers, we’ve reached the end of this journey through the world of React Edge! I know there’s still a sea of incredible features to explore, like simpler authentication options such as Basic and Bearer, and other tricks that make a developer’s day much happier. But hold on! The idea is to bring more detailed articles in the future to dive deep into each of these features.

Spoiler alert: soon, React Edge will be open source and properly documented! Balancing development, work, writing, and a little bit of social life isn’t easy, but the excitement of seeing this marvel in action, especially with the absurd speed provided by Cloudflare's infrastructure, is the fuel that keeps me going. So, stay tuned, because the best is yet to come! 🚀

In the meantime, if you want to start exploring and testing it right now, the package is already available on NPM: React Edge on NPM..

My email is feliperohdee@gmail.com, and I’m always open to feedback—this is just the beginning of this journey. Suggestions and constructive criticism are welcome. If you enjoyed what you read, share it with your friends and colleagues, and stay tuned for more updates. Thank you for reading this far, and see you next time! 🚀🚀🚀

Forem: Felipe Rohde

De Next.js a React Edge com Cloudflare Workers: Uma História de Libertação

A Gota D'água

A Alternativa com Cloudflare 😍

React Edge: O Framework React derivado de todas (ou quase) as dores de um desenvolvedor

Repensando o Desenvolvimento React para a era do Edge Computing

Com o React Edge, você não precisa:

A Magia do RPC Tipado

Compare isso com o Next.js/Vercel:

O Poder do useFetch: Onde a Mágica Acontece

Data Fetching Repensado

A Mágica da Multiplexação

SSR + Hidratação Perfeita

Além do useFetch: O arsenal completo

RPC: A Arte da Comunicação Cliente-Servidor

Segurança e Encapsulamento

Hierarquia de APIs RPC

Benefícios da Hierarquia

Um Sistema de i18n que Faz Sentido

Configuração Zero

Autenticação JWT que "Simplesmente Funciona"

Uso no Cliente: Zero Configuração

Por Que Isso é Revolucionário?

O Store Compartilhado

Como Funciona

Benefícios

Roteamento Elegante

Principais Recursos

Benefícios

Cache Distribuído com Edge Cache

Principais Recursos

Benefícios

Link: O Componente que Pensa à Frente

app.useContext: O Portal para o Edge

Principais Recursos do app.useContext

Por Que É Poderoso

app.useUrlState: Estado Sincronizado com a URL

Parâmetros

Benefícios

Aplicações Práticas

app.useStorageState: Estado Persistente

Opções de Persistência

Performance

Casos de Uso Comuns

app.useDebounce: Controle de Frequência

app.useDistinct: Estado sem Duplicatas

Principais Recursos

Benefícios

A CLI do React Edge: Potência na Ponta dos Dedos

Comandos Modulares e Flexíveis:

Casos de Uso em Produção

Conclusão

From Next.js to React Edge with Cloudflare Workers: A Story of Liberation

Quick Index

The Final Straw

The Alternative with Cloudflare 😍

React Edge: The React Framework Born from Every Developer’s Pain (or Almost)

Rethinking React Development for the Edge Computing Era

With React Edge, you no longer need to:

The Magic of Typed RPC

Compare this with Next.js/Vercel:

The Power of useFetch: Where the Magic Happens

Rethinking Data Fetching

The Magic of Multiplexing

SSR + Perfect Hydration

Beyond useFetch: The Complete Arsenal

RPC: The Art of Client-Server Communication

Security and Encapsulation

RPC API Hierarchies

Benefits of Hierarchies

A System of i18n That Makes Sense

Zero Configuration

JWT Authentication That "Just Works"

Client Usage: Zero Configuration

Why Is This Revolutionary?

The Shared Store

Example of Middleware and Store Usage

How It Works

Benefits

Elegant Routing

The Power of `useFetch`: Where the Magic Happens