# Comece com o OpenNext

O adaptador `@aziontech/opennextjs-azion` permite que você faça deploy de apps Next.js na Azion Web Platform. Este guia irá ajudá-lo a configurar um projeto Next.js novo ou existente para a Azion, configurar cache, desenvolver localmente e fazer o deploy para produção.

---

### Pré-requisitos

- [CLI Instalado](/pt-br/documentacao/produtos/azion-cli/visao-geral/#instalar-a-azion-cli).

---

#### Criando um novo app Next.js

Para criar um novo app Next.js pré-configurado para a Azion:

```sh
npx create-next-app@14.2.4 my-next-app --use-npm
cd my-next-app
npm install @aziontech/opennextjs-azion@latest
```

Ou use um template inicial:

- [Template Next.js + TypeScript + Tailwind](https://github.com/aziontech/azion-samples/tree/dev/templates/opennextjs/nextal-next-typescript-tailwind)
- [Node Playground (Next.js 13)](https://github.com/aziontech/bundler-examples/tree/main/examples/nextjs/node-playground-13)

---

#### Apps Next.js existentes

1. Instale o adaptador Azion:

```sh
npm install @aziontech/opennextjs-azion@latest
```

2. Configure `open-next.config.ts`:

Crie ou atualize `open-next.config.ts` no diretório raiz do seu projeto. Exemplo:

```ts
import { defineAzionConfig } from "@aziontech/opennextjs-azion";

export default defineAzionConfig({
  // Veja https://www.azion.com/pt-br/produtos/cache/ para opções avançadas
});
```

3. Atualize `tsconfig.json`:

:::warning
Seu `tsconfig.json` deve incluir ```json "moduleResolution": "bundler" ```. Isto é necessário para o comportamento correto de build e runtime.
:::

Se você encontrar problemas com ESM ou `open-next.config.ts`, pode ser necessário adicionar:

```json
"exclude": ["node_modules", "open-next.config.ts"]
```

Veja [Problemas Conhecidos](/pt-br/documentacao/runtime-api/frameworks-suportados/nextjs/#problemas-conhecidos) para mais detalhes.

1. Build e Deploy com Azion CLI:

- `azion build`: Constrói seu app para a Azion.
- `azion preview`: Executa uma pré-visualização local usando o Azion CLI.
- `azion deploy`: Faz deploy na Azion Web Platform usando deploy remoto.
  - ou `azion deploy --local` para fazer deploy na Azion Web Platform usando Deploy Local.

5. Configure cache e armazenamento:

Veja o [Guia de Cache](https://www.azion.com/pt-br/produtos/cache/) para saber como configurar o Azion Object Storage e Cache para ISR/SSG. Exemplo de configuração Azion:

```ts
AzionCache
Definição de tipo para a configuração de cache.
```

Propriedades:

| Propriedade | Tipo | Descrição |
| --- | --- | --- |
| nome | string | Nome da configuração de cache. |
| staleness? | boolean | Se permite conteúdo obsoleto. |
| queryStringSort? | boolean | Se organiza parâmetros de string de consulta. |
| métodos? | CacheMethods | Métodos HTTP para cache. |
| post? | boolean | Se faz cache de requisições POST. |
| opções? | boolean | Se faz cache de requisições OPTIONS. |
| navegador? | BrowserCacheConfig | Configurações de cache para navegador. |
| navegador.maxAgeSeconds | number \| string | Idade máxima para cache do navegador em segundos. |
| edge? | EdgeCacheConfig | Configurações de cache. |
| edge.maxAgeSeconds | number \| string | Idade máxima para cache em segundos. |
| cacheByCookie? | CacheByCookieConfig | Cache por configurações de cookie. |
| cacheByCookie.option | 'ignore' \| 'varies' \| 'whitelist' \| 'blacklist' | Opção de cache por cookie. |
| cacheByCookie.list? | string[] | Lista de cookies para uso em cache. |
| cacheByQueryString? | CacheByQueryStringConfig | Cache por configurações de string de consulta. |
| cacheByQueryString.option | 'ignore' \| 'varies' \| 'whitelist' \| 'blacklist' | Opção de cache por string de consulta. |
| cacheByQueryString.list? | string[] | Lista de parâmetros de string de consulta para uso em cache. |

```js
// azion.config.cjs
module.exports = {
  build: { preset: "opennextjs", polyfills: true },
  origin: [{ name: "origin-storage-default", type: "object_storage" }],
  functions: [{ name: "handler", path: ".edge/worker.js" }],
  cache: [
    {
      name: 'Default Cache',
      browser: { maxAgeSeconds: 3600 },
      edge: { maxAgeSeconds: 7200 },
    },
  ],
  rules: {
    request: [
      {
        name: "Set storage origin for _next/static",
        match: "^/_next/static/",
        behavior: { setOrigin: { name: "origin-storage-default", type: "object_storage" }, deliver: true },
      },
      {
        name: "Deliver Static Assets",
        match: ".(css|js|ttf|woff|woff2|pdf|svg|jpg|jpeg|gif|bmp|png|ico|mp4|json)$",
        behavior: { setOrigin: { name: "origin-storage-default", type: "object_storage" }, deliver: true },
      },
      {
        name: "Execute Function",
        match: "^/",
        behavior: { runFunction: "handler", forwardCookies: true },
      },
    ],
  },
};
```

---

### Desenvolvimento Local

Use o [Azion CLI](/pt-br/documentacao/produtos/azion-cli/visao-geral/) para desenvolvimento local:

```sh
azion dev
```

Isso executa sua aplicação localmente, simulando a plataforma Azion. Veja [Solução de Problemas](/pt-br/documentacao/produtos/guias/opennext/troubleshooting/) para dicas de depuração e monitoramento de logs.

---

### Implementação

Implemente seu app na Azion Web Platform:

```sh
azion deploy
```

Ou use o Azion CLI para implementar na Azion Web Platform usando implementação local:

```sh
azion deploy --local
```

---

### Melhores práticas e solução de problemas

- Veja [Problemas Conhecidos](/pt-br/documentacao/runtime-api/frameworks-suportados/nextjs/#problemas-conhecidos) para acessar notas de configuração importantes.
- Veja [Solução de Problemas](/pt-br/documentacao/produtos/guias/opennext/troubleshooting/) para dicas de desenvolvimento local, logs e depuração.
- Explore [Exemplos](/pt-br/documentacao/runtime-api/frameworks-suportados/nextjs/#exemplos) para projetos iniciais e templates.
- Para cache avançado, [veja Cache](https://www.azion.com/pt-br/produtos/cache/).

:::tip
Algumas APIs do Node.js ou Web podem não ser totalmente suportadas no ambiente de desenvolvimento local da Azion, mas funcionarão em produção. Se você encontrar problemas localmente, tente fazer o deploy antes de tentar uma depuração profunda.
:::

Agora você está pronto para construir, testar e implementar apps Next.js nas Functions Azion!

---