@gringow/gringow-nextjs 0.0.3 → 0.0.4

package/README.md

@@ -1,89 +1,221 @@
 # @gringow/gringow-nextjs
 
-⚠️ Experimental Next.js integration for Gringow. The current implementation is intentionally minimal and primarily
-targets Turbopack builds by running a cache build once at request time.
+[![npm version](https://img.shields.io/npm/v/@gringow/gringow-nextjs)](https://www.npmjs.com/package/@gringow/gringow-nextjs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## What it actually does today
-- Scans source files for `g\`...\`` template literals using the glob pattern from `gringow.config.*` (via
-  `@gringow/gringow` config loading).
-- On Turbopack, hooks into `headers()` and triggers a single cache build on first call.
-- The Webpack path currently returns the provided Next config unchanged (no hooks wired yet).
-- No CLI flags (`--gringow=build|clear|reset`) are implemented.
+⚠️ **Experimental** Next.js integration for Gringow AI-powered translations. Currently targets Turbopack with minimal build-time cache generation.
 
-If you need a production-ready workflow today, prefer the Vite plugin or the CLI cache builder.
+## ⚠️ Status: Experimental
+
+This package is in early development and provides basic functionality. For production use, consider:
+- **[@gringow/gringow-vite](https://www.npmjs.com/package/@gringow/gringow-vite)** - Production-ready Vite plugin
+- **[@gringow/cli](https://www.npmjs.com/package/@gringow/gringow-cli)** - CLI cache builder
+
+## Features
+
+- 🎯 **Turbopack-First** - Built for Next.js 15+ with Turbopack
+- 🔍 **Auto-Extraction** - Scans for `g` tagged templates
+- 💾 **Cache Building** - Generates translations on first request
+- ⚡ **Minimal Setup** - Simple configuration wrapper
+
+## Current Limitations
+
+- **Turbopack only** - Webpack integration is a stub (no build hooks)
+- **No CLI flags** - `--gringow=build|clear|reset` not implemented
+- **Headers hook** - Cache builds during `headers()` call (not ideal)
+- **No cache pruning** - Stale entries not removed automatically
+
+**Contributions welcome** to improve Webpack support and add proper build hooks!
 
 ## Installation
+
 ```bash
-pnpm add @gringow/gringow-nextjs
-# npm install @gringow/gringow-nextjs
-# yarn add @gringow/gringow-nextjs
+# Using pnpm
+pnpm add @gringow/gringow-nextjs @gringow/gringow @gringow/gringow-react
+
+# Using npm
+npm install @gringow/gringow-nextjs @gringow/gringow @gringow/gringow-react
+
+# Using yarn
+yarn add @gringow/gringow-nextjs @gringow/gringow @gringow/gringow-react
 ```
 
-## Usage (Turbopack-first)
-```ts
+## Quick Start
+
+### 1. Configure Next.js
+
+```typescript
 // next.config.ts
 import type { NextConfig } from 'next'
 import GringowNextjsPlugin from '@gringow/gringow-nextjs'
 
-const withGringow = GringowNextjsPlugin({ debug: process.env.NODE_ENV === 'development' })
+const withGringow = GringowNextjsPlugin({
+  debug: process.env.NODE_ENV === 'development'
+})
 
 const nextConfig: NextConfig = {
-  // your config
+  // Your Next.js configuration
+  experimental: {
+    turbo: {}, // Turbopack recommended
+  },
 }
 
 export default withGringow(nextConfig)
 ```
 
-Run your app normally (`pnpm dev`). The first time the `headers` function resolves (Turbopack), the plugin will:
-
-1) read `gringow.config.*` for `globby` and LLM settings,
-2) globby-scan files, collecting `g\`...\`` occurrences,
-3) call the core Gringow runtime to populate `gringow/gringow.json`.
+### 2. Create Gringow Config
 
-## Options
-```ts
-type GringowNextjsPluginOptions = {
-  debug?: boolean // prints when cache building starts/completes
+```javascript
+// gringow.config.js
+export default {
+  llm: {
+    choice: 'huggingface',
+    model: 'Xenova/nllb-200-distilled-600M',
+  },
+  languages: ['pt-BR', 'es-ES', 'fr-CA'],
+  sourceLanguage: 'en-US',
+  globby: './app/**/*.{ts,tsx}', // Adjust to your structure
 }
 ```
 
-## Status & limitations
-- Turbopack only, and even there it runs during `headers()` rather than build hooks.
-- Webpack integration is a stub (no cache build hooks yet).
-- Cache pruning and `--gringow` flags are not implemented.
+### 3. Use in Components
 
-Contributions to complete the Webpack path or to add build-time hooks are welcome.
-
-## License
-MIT
+```tsx
+// app/page.tsx
+import { g } from '@gringow/gringow-react'
 
 export default function HomePage() {
-  const name = 'John'
+  const name = 'Alice'
   
   return (
     <div>
-      <h1>{Gringow`Welcome to our website, ${name}!`}</h1>
-      <p>{Gringow`This text will be automatically translated.`}</p>
+      <h1>{g`Welcome ${name}!`}</h1>
+      <p>{g`This text will be automatically translated.`}</p>
     </div>
   )
 }
 ```
 
-### 5. Build your cache
+### 4. Run Development Server
+
 ```bash
-# Pre-populate the translation cache
-npm run build -- --gringow=build
+pnpm dev
+
+# First request triggers cache build
+# Translations stored in ./gringow/gringow.json
+```
+
+## Configuration
+
+### Plugin Options
+
+```typescript
+interface GringowNextjsPluginOptions {
+  debug?: boolean  // Log cache build operations (default: false)
+}
+```
+
+**Example:**
+```typescript
+const withGringow = GringowNextjsPlugin({ debug: true })
+```
 
-# Or clear and rebuild
-npm run build -- --gringow=reset
+### Gringow Config
+
+The plugin reads your `gringow.config.js`:
+
+- **`globby`** - File patterns to scan (e.g., `'./app/**/*.{ts,tsx}'`)
+- **`llm.*`** - LLM provider configuration
+- **`languages`** - Target translation languages
+- **`cache.dir`** - Cache directory (default: `'./gringow'`)
+
+See [@gringow/gringow](https://www.npmjs.com/package/@gringow/gringow) for complete options.
+
+## How It Works
+
+### Turbopack Flow
+
+1. **Plugin wraps** Next.js config with Gringow middleware
+2. **Headers hook** - First `headers()` call triggers cache build
+3. **File scanning** - Uses `globby` pattern from config
+4. **Extraction** - Finds all `g` tagged templates
+5. **Translation** - Calls core library to translate
+6. **Cache write** - Stores in `./gringow/gringow.json`
+
+### Webpack Flow
+
+Currently returns config unchanged. Build hooks not yet implemented.
+
+## Usage Examples
+
+### App Router with Server Components
+
+```tsx
+// app/page.tsx
+import { g } from '@gringow/gringow-react'
+
+export default async function Page() {
+  const data = await fetchData()
+  
+  return (
+    <main>
+      <h1>{g`Welcome to our platform`}</h1>
+      <p>{g`You have ${data.count} items`}</p>
+    </main>
+  )
+}
 ```
 
-The translations will be stored in `./gringow/gringow.json` and automatically used in your application.
+### Pages Router
+
+```tsx
+// pages/index.tsx
+import { g } from '@gringow/gringow-react'
+import type { NextPage } from 'next'
+
+const HomePage: NextPage = () => {
+  return (
+    <div>
+      <h1>{g`Home Page`}</h1>
+      <p>{g`Welcome back!`}</p>
+    </div>
+  )
+}
 
-## How it works
-- `transform`: checks each loaded module, finds `g\`...\`` usage, and seeds the translation cache via `@gringow/gringow`.
-- `buildEnd`: prunes cache entries that no longer exist in source and backfills any new strings discovered by static scanning.
-- `buildStart`: watches for the `--gringow=` flag to run cache maintenance chores outside of normal Vite flows.
+export default HomePage
+```
+
+### Client Components
+
+```tsx
+'use client'
+
+import { g, changeLanguage } from '@gringow/gringow-react'
+import { useEffect } from 'react'
+
+export function LanguageSwitcher() {
+  useEffect(() => {
+    // Initialize Gringow store on client
+    import('@gringow/gringow-react/browser')
+    import('@gringow/gringow-react/store').then(({ GringowStore }) => {
+      GringowStore.cacheUrl = '/gringow/gringow.json'
+      GringowStore.language = 'en-US'
+      GringowStore.fetchCache()
+    })
+  }, [])
+
+  return (
+    <div>
+      <button onClick={() => changeLanguage('en-US')}>
+        {g`English`}
+      </button>
+      <button onClick={() => changeLanguage('pt-BR')}>
+        {g`Portuguese`}
+      </button>
+    </div>
+  )
+}
+```
 
 ## Development scripts
 ```bash
@@ -93,3 +225,89 @@ pnpm run watch   # Continuous rebuild for local development
 
 ## License
 MIT © Renato Gaspar
+
+## Workarounds & Tips
+
+### Pre-Build Cache
+
+Since CLI flags aren't implemented, generate cache before deployment:
+
+```bash
+# Use CLI to build cache
+pnpm gringow cache list  # or use Vite plugin
+```
+
+### Commit Cache File
+
+For faster deployments, commit `gringow/gringow.json`:
+
+```bash
+git add gringow/gringow.json
+git commit -m "Add translation cache"
+```
+
+### Use Vite for Development
+
+For better DX, develop with Vite and deploy with Next.js:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build:translations": "vite build --gringow=build",
+    "build": "pnpm build:translations && next build"
+  }
+}
+```
+
+## Known Issues
+
+- **Webpack**: No build hooks - returns config unchanged
+- **CLI flags**: `--gringow=build|clear|reset` not supported
+- **Cache pruning**: Stale entries not automatically removed
+- **Build timing**: Cache builds on first request, not at build time
+
+## Roadmap
+
+- [ ] Proper Webpack integration with build hooks
+- [ ] CLI flags support (`--gringow=build|clear|reset`)
+- [ ] Build-time cache generation (not request-time)
+- [ ] Automatic cache pruning
+- [ ] Better error handling and logging
+
+**Want to contribute?** PRs welcome on [GitHub](https://github.com/rntgspr/gringow)!
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the plugin
+pnpm run build
+
+# Watch mode
+pnpm run watch
+```
+
+## Related Packages
+
+- **[@gringow/gringow](https://www.npmjs.com/package/@gringow/gringow)** - Core translation library
+- **[@gringow/gringow-react](https://www.npmjs.com/package/@gringow/gringow-react)** - React bindings
+- **[@gringow/gringow-vite](https://www.npmjs.com/package/@gringow/gringow-vite)** - Production-ready Vite plugin (recommended)
+- **[@gringow/gringow-shadow](https://www.npmjs.com/package/@gringow/gringow-shadow)** - Web Component layer
+- **[@gringow/cli](https://www.npmjs.com/package/@gringow/gringow-cli)** - CLI tool
+
+## Resources
+
+- [Documentation](https://gringow.dev)
+- [GitHub Repository](https://github.com/rntgspr/gringow)
+- [Vite Example](https://github.com/rntgspr/gringow/tree/main/example-gringow-vite)
+
+## License
+
+MIT © [Renato Gaspar](https://github.com/rntgspr)
+
+---
+
+**Questions?** Open an issue on [GitHub](https://github.com/rntgspr/gringow/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gringow/gringow-nextjs",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "A Next.js plugin for Gringow AI-powered translation tool",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",
@@ -42,8 +42,8 @@
     "globby": "14.1.0",
     "react": "^19.2.0",
     "webpack": "^5.102.1",
-    "@gringow/gringow": "0.1.3",
-    "@gringow/gringow-react": "0.0.8"
+    "@gringow/gringow": "0.1.4",
+    "@gringow/gringow-react": "0.0.9"
   },
   "peerDependencies": {
     "next": ">=15.0.0"