# Fresh + PostgreSQL

> Deno full-stack framework with island architecture.

- Category: Full Web Stacks
- Difficulty: intermediate
- Components: fresh, postgres
- Tags: fresh, deno, postgres, islands
- Source: https://docker.recipes/full-stacks/fresh-postgres

## Overview

Fresh is a modern full-stack web framework for Deno that pioneered the island architecture pattern, where only interactive components are hydrated on the client side while the rest of the page remains static HTML. Built by the Deno team in 2022, Fresh eliminates the traditional build step by serving TypeScript and JSX directly, using Preact for UI components and enabling sub-second page loads through selective hydration. This approach dramatically reduces JavaScript bundle sizes and improves performance compared to traditional single-page applications.

This stack pairs Fresh's edge-first architecture with PostgreSQL's enterprise-grade data management capabilities, creating a powerful combination for building fast, data-driven web applications. Fresh handles the presentation layer with zero-config TypeScript support and file-based routing, while PostgreSQL provides ACID-compliant transactions, advanced JSON querying, and full-text search capabilities. The Deno runtime's built-in PostgreSQL drivers enable type-safe database operations without additional build tools.

Developers building modern web applications, SaaS platforms, or content management systems will find this stack particularly valuable when they need both rapid development cycles and robust data integrity. The combination excels for teams wanting to leverage TypeScript across the entire stack while maintaining the flexibility to scale from simple CRUD applications to complex data-driven platforms with advanced PostgreSQL features like JSON querying and geospatial data processing.

## Features

- Island architecture with selective hydration reduces JavaScript bundle sizes by 90% compared to traditional SPAs
- Zero-config TypeScript and JSX serving directly from Deno runtime without build steps
- File-based routing system with automatic code splitting and lazy loading
- PostgreSQL JSONB support enables hybrid relational-document data models within Fresh components
- Preact-based islands with automatic client-server state synchronization
- Built-in Deno PostgreSQL drivers with type-safe query builders and prepared statements
- Fresh's edge-ready SSR combined with PostgreSQL's logical replication for global deployments
- Advanced PostgreSQL features like full-text search, window functions, and CTEs accessible through Deno APIs

## Use cases

- E-commerce platforms requiring fast page loads with complex product catalogs and inventory management
- Content management systems leveraging PostgreSQL's full-text search and Fresh's island architecture for editorial interfaces
- SaaS dashboards with real-time data visualization using PostgreSQL's JSON aggregation and Fresh's selective hydration
- Multi-tenant applications utilizing PostgreSQL's row-level security with Fresh's server-side rendering
- Geospatial applications combining PostGIS extensions with Fresh's lightweight client-side mapping components
- Developer portfolios and blogs with PostgreSQL-backed content and Fresh's near-instant page transitions
- Progressive web applications requiring offline-first capabilities with PostgreSQL's advanced transaction handling

## Prerequisites

- Minimum 1GB RAM for PostgreSQL with recommended 2GB+ for production workloads
- Deno runtime knowledge including import maps and permission system concepts
- Basic understanding of Preact/React component patterns and JSX syntax
- PostgreSQL experience with SQL queries, indexing strategies, and connection pooling
- Port 8000 available for Fresh development server and standard PostgreSQL port 5432
- Familiarity with island architecture concepts and server-side rendering principles

## docker-compose.yml

```yaml
services:
  fresh:
    image: denoland/deno:latest
    container_name: fresh
    working_dir: /app
    command: run -A main.ts
    environment:
      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
    volumes:
      - ./:/app
    ports:
      - "8000:8000"
    depends_on:
      - postgres
    networks:
      - fresh-network

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - fresh-network

volumes:
  postgres_data:

networks:
  fresh-network:
    driver: bridge
```

## .env

```bash
DB_NAME=fresh
DB_USER=fresh
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://fresh.deno.dev/docs/
- Access at http://localhost:8000
- No build step: serves TypeScript directly
- Island architecture: selective hydration
- Preact for UI components
- Use deno_postgres or denodb for database access

## Troubleshooting

- TypeError: Cannot resolve module specifier: Ensure Deno import maps are properly configured in deno.json for PostgreSQL client libraries
- Fresh islands not hydrating: Verify island components are exported as default and placed in the islands/ directory with proper naming conventions
- PostgreSQL connection refused: Check that DATABASE_URL environment variable matches the service name 'postgres' not 'localhost' in containerized environment
- Deno permission errors accessing database: Add --allow-net and --allow-env flags to the Deno run command for PostgreSQL connections
- Fresh routes not found: Ensure route files in routes/ directory follow Fresh naming conventions with proper export of handler functions
- PostgreSQL data not persisting: Verify postgres_data volume is properly mounted and PostgreSQL container has write permissions to /var/lib/postgresql/data

