Big Year: The Google Calendar Hack Developers Are Secretly Using

Your Google Calendar is lying to you.

Every day, you open that cramped monthly grid. You squint at overlapping event blocks. You click forward, forward, forward—desperately trying to see the bigger picture of your year. Birthdays, vacations, project launches, personal milestones—all scattered across twelve tiny panes that force you to piece together your life like a broken puzzle.

Sound familiar?

Here's the brutal truth: Google Calendar was never designed for visual year planning. It's a scheduling tool masquerading as a life organizer. And developers—the very people building the future—have been stuck with this inadequate interface for planning their own time.

But what if you could see your entire year at once? Not as a list. Not as cramped boxes. But as a beautiful, scrollable, full-screen visualization of every all-day event that matters?

Enter Big Year—the open-source project that's making developers abandon their calendar anxiety forever. Built by Gabriel Valdivia and quietly gaining traction among productivity-obsessed engineers, this tool exposes a secret that Google never wanted you to realize: your calendar data deserves a better stage.

In this deep dive, I'll show you exactly how Big Year works, why it's technically brilliant, and how you can deploy your own instance in under 30 minutes. No more calendar claustrophobia. No more missed patterns. Just your year, finally visible.

What Is Big Year?

Big Year is an open-source web application that reimagines Google Calendar as a full-year visualization tool. Created by designer-developer Gabriel Valdivia, it strips away the noise of hourly scheduling and surfaces only what truly matters for long-term planning: all-day events.

The concept is deceptively simple yet profoundly different from anything Google offers natively. While Google Calendar locks you into month-by-month views with microscopic day cells, Big Year explodes your calendar across the entire viewport—every day of the year visible simultaneously, events rendered as clean visual markers you can absorb in a single glance.

Why it's trending now:

The developer community has reached a tipping point with productivity tools. We're exhausted by SaaS subscriptions, privacy compromises, and interfaces designed for corporate meetings rather than personal clarity. Big Year hits a nerve because it's self-hostable, open-source, and radically focused. No feature bloat. No data mining. Just your calendar, beautifully reimagined.

Built on modern web technologies—Next.js^{↗ Bright Coding Blog}, NextAuth.js, PostgreSQL^{↗ Bright Coding Blog}, and the Google Calendar API—Big Year represents a new breed of developer tools: sophisticated enough for production use, simple enough for personal deployment. The repository has become a stealth favorite among indie hackers and productivity enthusiasts who want control without complexity.

The project's philosophy? Your time is a landscape, not a spreadsheet. And landscapes are meant to be seen whole.

Key Features That Make Big Year Insane

Let's dissect what makes this tool technically compelling beyond the surface appeal:

🔒 Secure OAuth 2.0 Integration with NextAuth.js

Big Year leverages NextAuth.js for bulletproof authentication, handling the entire Google OAuth flow including automatic token refresh. The refresh token mechanism means you authenticate once and forget about it—no manual re-authorization dance every few weeks. The implementation requests minimal scopes (calendar.readonly for basic operation), following the principle of least privilege.

🗄️ PostgreSQL Backend with Production-Ready Architecture

Unlike toy projects that store everything in memory or JSON files, Big Year uses PostgreSQL for persistent session and user data. This isn't accidental complexity—it's foresight. The database layer supports multi-user scenarios, session management, and scales from your laptop to Vercel's edge network without architectural changes.

📐 Viewport-Optimized Full-Year Visualization

The calendar auto-fills the entire viewport using responsive CSS techniques. This isn't just aesthetic polish—it's information design. By using 100vw and 100vh calculations, every day cell maintains readable proportions regardless of screen size. The implementation likely uses CSS Grid or Flexbox with dynamic cell sizing, though the exact technique rewards exploration of the source.

🎯 Intelligent All-Day Event Filtering

Here's where the technical sophistication shines. Big Year specifically filters for events where start.date exists rather than start.dateTime. This distinction matters enormously: start.date indicates all-day events in the Google Calendar API, while start.dateTime marks timed events. By filtering at the API level, Big Year eliminates client-side noise and reduces payload size.

🚀 Vercel-Optimized Deployment Pipeline

The entire project is architected for Vercel's serverless platform. Environment variable configuration, redirect URI handling, and domain verification workflows are all documented for frictionless deployment. This isn't an afterthought—it's platform-native engineering.

🔄 Automatic Token Refresh Architecture

Google OAuth access tokens expire. Big Year handles this transparently using refresh tokens stored securely via NextAuth.js's database adapter. The implementation means your calendar stays synchronized without user intervention—a critical reliability feature for any production calendar integration.

Use Cases Where Big Year Absolutely Dominates

1. Personal Year Planning & Life Visualization

Track vacations, birthdays, anniversaries, and personal milestones across the full year. See patterns in your time off. Notice when you're overcommitting. The yearly view reveals rhythms that monthly grids obscure—like clustering all your PTO in Q2 or neglecting personal time entirely during crunch periods.

2. Content & Editorial Calendar Management

Bloggers, newsletter writers, and content creators use all-day events to mark publication schedules, campaign launches, and content themes. Big Year transforms this into a strategic overview. Spot gaps in your publishing frequency. Align content with seasonal trends. Share the visualization with stakeholders who need the big picture without hourly detail.

3. Remote Team Availability & Holiday Coordination

Distributed teams struggle with visibility across time zones and holiday calendars. By having team members share a dedicated Google Calendar with all-day vacation entries, Big Year becomes a team-wide availability dashboard. No more Slack pings asking "when are you back?"—it's visible in the yearly landscape.

4. Project Milestone & Deadline Tracking

Product managers and indie hackers mark ship dates, beta launches, and version releases as all-day events. The yearly view exposes pipeline congestion—too many launches in one quarter, dangerous gaps in delivery cadence. It's strategic planning that Gantt charts wish they could achieve with this elegance.

5. Habit & Goal Tracking Integration

Sync with automation tools (Zapier, Make, custom scripts) that create all-day events for habit streaks, goal deadlines, or quarterly objectives. Big Year becomes a visual scoreboard for your annual ambitions. The full-year perspective combats the myopia of weekly productivity systems.

Step-by-Step Installation & Setup Guide

Ready to escape calendar prison? Here's your complete deployment path from zero to yearly visibility.

Prerequisites

• Node.js 18+ installed
• A Google Cloud project with OAuth 2.0 credentials
• PostgreSQL database (local or hosted)
• Vercel account (for production deployment)

Local Development Setup

Step 1: Clone and install dependencies

# Clone the repository
git clone https://github.com/gabrielvaldivia/big-year.git
cd big-year

# Install dependencies
npm install

Step 2: Configure environment variables

Create .env in the project root:

# Database connection - use local PostgreSQL or hosted service like Neon/Supabase
DATABASE_URL=postgresql://username:password@localhost:5432/bigyear

# NextAuth configuration - must match your deployment URL exactly
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=replace-with-a-strong-random-string

# Google OAuth credentials from Google Cloud Console
GOOGLE_CLIENT_ID=your-google-oauth-client-id
GOOGLE_CLIENT_SECRET=your-google-oauth-client-secret

Generate a secure NEXTAUTH_SECRET:

# On macOS/Linux
openssl rand -base64 32

# On Windows (PowerShell)
[System.Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 } | ForEach-Object { [byte]$_ }))

Step 3: Configure Google OAuth application

In Google Cloud Console:

1. Create or select your project
2. Navigate to APIs & Services → Credentials
3. Click Create Credentials → OAuth client ID
4. Select Web application as the type
5. Add authorized redirect URI:

   http://localhost:3000/api/auth/callback/google
   

6. Enable the Google Calendar API in APIs & Services → Library
7. Note your Client ID and Client Secret for the .env file

Step 4: Initialize the database

# Ensure your PostgreSQL database exists and is accessible
# NextAuth.js will automatically create required tables on first run
# Verify connection with:
npx prisma db push  # if using Prisma (verify in project)

Step 5: Launch the development server

npm run dev

Open http://localhost:3000, authenticate with Google, and your yearly calendar appears.

Production Deployment on Vercel

Step 1: Configure Vercel environment variables

In your Vercel project dashboard, navigate to Settings → Environment Variables:

Critical: NEXTAUTH_URL must match your deployment URL exactly, including https://.

Step 2: Update Google OAuth for production

In Google Cloud Console, add your production redirect URI:

https://your-domain.com/api/auth/callback/google

Step 3: Deploy

# Using Vercel CLI
vercel --prod

# Or push to Git with Vercel Git integration

REAL Code Examples from the Repository

Let's examine actual implementation patterns from Big Year's codebase, with detailed technical analysis.

Example 1: Environment Configuration Structure

The .env file establishes the complete configuration contract:

# Database connection string for PostgreSQL
# Supports local development or hosted providers (Neon, Supabase, Railway)
DATABASE_URL=your-postgresql-database-url

# NextAuth.js base URL - CRITICAL for OAuth callback generation
# Must match the exact URL users access, including protocol
NEXTAUTH_URL=http://localhost:3000

# Cryptographic secret for JWT encryption and session signing
# Generate with: openssl rand -base64 32
NEXTAUTH_SECRET=replace-with-a-strong-random-string

# Google OAuth 2.0 credentials from Google Cloud Console
# Create at: https://console.cloud.google.com/apis/credentials
GOOGLE_CLIENT_ID=your-google-oauth-client-id
GOOGLE_CLIENT_SECRET=your-google-oauth-client-secret

Technical insight: The NEXTAUTH_URL requirement is non-negotiable. NextAuth.js uses this to construct the callback URL sent to Google's OAuth server. A mismatch here produces the infamous "redirect_uri_mismatch" error that torments OAuth implementations. The explicit http://localhost:3000 for development prevents the common mistake of hardcoding production URLs.

Example 2: Google OAuth Scopes Configuration

The required scopes reveal the application's minimal permission philosophy:

openid email profile https://www.googleapis.com/auth/calendar.readonly

Breaking this down:

• openid: Enables OpenID Connect authentication flow
• email: Retrieves user's email address for account identification
• profile: Access to basic profile information (name, picture)
• https://www.googleapis.com/auth/calendar.readonly: Read-only calendar access—deliberately restrictive

Critical implementation note: The README documents that some configurations may include https://www.googleapis.com/auth/calendar.events, which is a sensitive scope requiring app verification. The read-only scope avoids this complexity for basic functionality.

Example 3: Production Vercel Environment Configuration

The production setup demonstrates platform-specific optimization:

# Production environment variables for Vercel deployment
NEXTAUTH_URL=https://bigyear.app  # Must match custom domain exactly
NEXTAUTH_SECRET=[openssl-generated-secret]  # Cryptographically secure random
GOOGLE_CLIENT_ID=[production-client-id]  # Separate from development credentials
GOOGLE_CLIENT_SECRET=[production-client-secret]
DATABASE_URL=[vercel-postgres-or-external]  # Vercel Postgres or external provider

Deployment architecture insight: Using separate OAuth credentials for production versus development is a security best practice. If development credentials leak, production remains uncompromised. The NEXTAUTH_URL exact-match requirement prevents subtle bugs where https://bigyear.app and https://www.bigyear.app are treated as different origins.

Example 4: Domain Verification Route Handler

For Google Search Console verification on Vercel, the repository provides a Next.js App Router pattern:

// app/google[your-verification-code]/route.ts
// Dynamic route handler for Google site verification

import { NextResponse } from "next/server";

export async function GET() {
  // Return the exact HTML content Google requires for verification
  // The meta tag proves domain ownership without file system access
  return new NextResponse(
    '<meta name="google-site-verification" content="YOUR_CONTENT_HERE" />',
    {
      headers: { 
        // Explicit content-type prevents browser misinterpretation
        "Content-Type": "text/html",
      },
    }
  );
}

Advanced pattern analysis: This route handler solves a Vercel-specific constraint: the serverless platform doesn't expose traditional file systems for static HTML uploads. By using a dynamic route with NextResponse, the verification content is generated on-demand. The [your-verification-code] dynamic segment allows multiple verification codes without code changes.

The next.config.mjs rewrite (mentioned but not fully shown) would map the .html extension Google expects to the clean route:

// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  async rewrites() {
    return [
      {
        source: '/google:code*.html',
        destination: '/google:code*',
      },
    ];
  },
};

export default nextConfig;

This rewrite pattern preserves Google's expected URL structure while leveraging Next.js App Router conventions.

Example 5: Event Filtering Logic (Documented Behavior)

While the exact API call isn't shown in the README, the filtering behavior is precisely specified:

// Conceptual implementation based on documented behavior:
// Only events with start.date (all-day) are included
// Events with start.dateTime (timed) are excluded

const allDayEvents = calendarEvents.filter(event => {
  // Google Calendar API distinguishes all-day vs timed events
  // by the presence of 'date' vs 'dateTime' properties
  return event.start.date !== undefined && 
         event.start.dateTime === undefined;
});

// Result: Clean yearly view without hourly clutter

API design insight: This filtering at the data layer rather than presentation layer is architecturally sound. It reduces network payload, simplifies client-side rendering logic, and maintains semantic clarity. The Google Calendar API's dual property approach (date vs dateTime) is an elegant solution to the all-day event representation problem.

Advanced Usage & Best Practices

Security Hardening

• Rotate NEXTAUTH_SECRET quarterly using the openssl command. Treat this like a database password.
• Use separate Google OAuth projects for development, staging, and production. Never reuse production credentials locally.
• Enable Google's Cross-Account Protection in OAuth consent screen settings to prevent session hijacking across Google accounts.

Performance Optimization

• Implement incremental static regeneration (ISR) for public calendar views if you add sharing features. Cache the yearly view and revalidate hourly.
• Use connection pooling for PostgreSQL—critical for Vercel's serverless functions. Services like PgBouncer or Supabase's built-in pooling prevent connection exhaustion.

Customization Patterns

• Theming: Override CSS custom properties for brand alignment. The viewport-based layout likely uses CSS variables for colors, spacing, and typography.
• Event categorization: Extend the data model to support Google Calendar's colorId property, rendering different event types with visual distinction.
• Multi-calendar support: The Google Calendar API supports multiple calendar lists. Extend the auth scope and UI to aggregate across personal, work, and shared calendars.

Monitoring & Reliability

• Log OAuth token refresh failures to catch Google API rate limits or credential expiration.
• Set up Vercel Analytics to track actual usage patterns and identify performance bottlenecks.

Comparison with Alternatives

The verdict: Big Year occupies a unique position—it's the only tool that combines true yearly visualization, complete data sovereignty, and zero ongoing costs. The trade-off is self-hosted responsibility, but for developers, that's a feature, not a bug.

FAQ

Is Big Year free to use?

Yes, completely. It's open-source under the repository license. You host it yourself, so the only costs are your infrastructure (Vercel's free tier handles personal use; PostgreSQL can be free on Neon or Supabase).

Does Big Year access my private calendar events?

Only all-day events, and only with explicit OAuth permission. The calendar.readonly scope means no write access. Your data never touches the developer's servers—everything stays in your self-hosted instance.

Can I use Big Year without technical knowledge?

Basic deployment requires familiarity with Git, environment variables, and Google Cloud Console. However, the documentation is exceptionally detailed. Non-developers might need assistance with initial setup, but maintenance is minimal.

Why does Google show "This app is blocked" warnings?

This occurs when the OAuth app remains in "Testing" mode or requests sensitive scopes without verification. The README includes extensive troubleshooting—most commonly, you need to click Publish App in the OAuth consent screen settings and wait 5-10 minutes.

Does Big Year work with Apple Calendar or Outlook?

Not directly. It's designed for Google Calendar's API. However, you can sync Apple Calendar or Outlook to Google Calendar using their respective sync features, then use Big Year as the visualization layer.

How do I update Big Year when new versions release?

Standard Git workflow: git pull origin main, run any new migrations, and redeploy. The project follows semantic versioning practices for breaking changes.

Can multiple users access my Big Year instance?

Yes, through NextAuth.js's multi-user session support. Each user authenticates independently with their Google account. The PostgreSQL database manages user separation.

Conclusion

Big Year is more than a calendar visualization—it's a statement about how developers deserve tools that respect their time, their data, and their intelligence. In an era of surveillance capitalism and subscription fatigue, Gabriel Valdivia's creation proves that open-source craftsmanship can outperform billion-dollar products at the specific jobs that matter.

The yearly view isn't a gimmick. It's a cognitive revolution. Seeing your entire year transforms how you plan, how you commit, and how you reflect. Patterns emerge. Trade-offs become visible. You stop living month-to-month and start designing your time with intention.

Is it perfect? No. It requires technical setup. It demands self-hosting responsibility. But for developers who've already accepted that complexity in exchange for control, Big Year delivers something priceless: a calendar that actually shows you your life.

Ready to see your year differently?

👉 Star Big Year on GitHub — clone it, deploy it, make it yours. The yearly view you've been missing is one npm install away.

Your future self, looking back at a beautifully planned year, will thank you.