next-django 0.5.5

File-system routing para Django, inspirado no Next.js App Router.

🚀 Next-Django

A Developer Experience (DX) mágica do Next.js App Router, construída em cima da fundação sólida e robusta do Django.

O next-django elimina a necessidade de configurar urls.py, gerenciar dezenas de apps fragmentados e lidar com templates confusos. Ele traz roteamento baseado em arquivos (File-System Routing), componentes UI nativos, APIs automáticas e navegação instantânea SPA com zero dor de cabeça.

---

✨ Funcionalidades Principais

• ⚡ NOVO: Navegação SPA (Zero JS): O framework já vem com HTMX pré-configurado. Use o componente <c-ui.link href="/rota"> e navegue entre as páginas instantaneamente, sem recarregar o navegador. A exata sensação de velocidade do Next.js, mas com HTML puro!
• 📁 File-System Routing (UI): Esqueça o urls.py. Crie uma pasta app/sobre/ com um arquivo page.py e a rota /sobre/ é gerada automaticamente. Suporta rotas dinâmicas como [int:id]!
• 🥷 API Routes (Zero Config): Crie arquivos na pasta api/ e tenha endpoints RESTful gerados automaticamente usando o poder do Django Ninja (com Swagger UI incluso).
• 🧩 Componentização (UI): Suporte nativo a componentes reutilizáveis estilo React/Vue através do django-cotton. Crie components/ui/button.html e use como <c-ui.button> em qualquer lugar.
• 🗄️ Modelos Desacoplados: Uma pasta models/ centralizada na raiz do projeto (estilo Prisma/TypeORM), dando adeus à obrigação de ter modelos presos dentro de sub-aplicativos do Django.
• 🪄 CLI Automático: Um único comando (next-django init) injeta as configurações no seu settings.py, atualiza seu urls.py e gera toda a arquitetura base com Tailwind CSS pré-configurado.

---

🚀 Quick Start (Passo a Passo)

Comece um projeto moderno em menos de 1 minuto:

1. Crie um projeto Django padrão (se ainda não tiver):

# Crie a pasta e o ambiente virtual
mkdir meu_app && cd meu_app
python -m venv venv
source venv/bin/activate  # (No Windows: venv\Scripts\activate)

# Instale o Django e inicie o projeto na pasta atual (.)
pip install django
django-admin startproject core .

2. Instale o Next-Django:

pip install next-django

3. Inicialize a Mágica (Zero Config):

next-django init

(Este comando cria as pastas app/, api/, components/ e models/, e auto-configura o seu settings.py e urls.py!)

4. Rode o servidor:

python manage.py runserver

Acesse http://127.0.0.1:8000 e veja seu novo framework em ação!

---

🏗️ Como utilizar a Estrutura

Ao rodar o next-django init, você ganha a seguinte arquitetura:

meu_projeto/
├── app/                  # Rotas de interface (Páginas HTML)
├── api/                  # Rotas de API (JSON/REST)
├── components/           # Componentes visuais reutilizáveis
├── models/               # Banco de dados centralizado
├── core/                 # Configurações originais do Django
└── manage.py

1. Criando Páginas (Pasta app/)

O roteamento segue a estrutura de pastas. O arquivo que renderiza a tela deve se chamar page.py e conter uma função chamada page.

Dica de Ouro: O caminho no render() deve sempre espelhar a pasta onde o arquivo está!

Exemplo de app/sobre/page.py:

from django.shortcuts import render

def page(request):
    # O caminho do template reflete a pasta!
    return render(request, 'sobre/page.html', {"titulo": "Sobre Nós"})

2. Navegação Instantânea (HTMX)

Para navegar entre as páginas sem a tela piscar (SPA), não use a tag <a> normal. Use o componente nativo de link do Next-Django:

<c-ui.link href="/sobre">
    Ir para a página Sobre
</c-ui.link>

3. Criando APIs (Pasta api/)

Cada arquivo criado em api/ (exceto __init__.py) vira uma rota base. O arquivo precisa instanciar um Router do Django Ninja na variável router.

Exemplo de api/produtos.py (Gera a rota /api/produtos/):

from ninja import Router

router = Router()

@router.get("/")
def listar_produtos(request):
    return [{"id": 1, "nome": "Teclado Mecânico"}]

Acesse http://127.0.0.1:8000/api/docs para ver o Swagger gerado automaticamente!

4. Usando Componentes (Pasta components/)

Todo arquivo .html colocado aqui vira uma tag customizada.

• Arquivo: components/ui/card.html
• Como usar no seu app/page.html:

<c-ui.card>
    <h2>Conteúdo do Card</h2>
</c-ui.card>

5. Gerenciando Modelos (Pasta models/)

Crie seus modelos separadamente, por exemplo, models/produto.py. Atenção: Para o Django reconhecer seu modelo na hora de rodar as migrações, você precisa importá-lo no arquivo models/__init__.py:

# models/__init__.py
from .produto import Produto

Depois, basta rodar python manage.py makemigrations e python manage.py migrate normalmente!

---

🤝 Contribuindo

Pull requests são muito bem-vindos! Para mudanças maiores, por favor, abra uma issue primeiro para discutirmos o que você gostaria de mudar.

📄 Licença

MIT License - Sinta-se livre para usar, modificar e distribuir.