SharedJournal

A Next.js journal application built with the App Router, featuring user authentication and database integration.

Getting Started

First, run the development server:

npm run dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying src/app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.

Code Quality

• Run lint checks: npm run lint
• Format all files: npm run format
• Check formatting in CI or pre-commit: npm run format:check

ESLint is used for code-quality and correctness checks, while Prettier handles code formatting.

Setup

Environment Variables

Create a .env.local file in the root of your project with the following variables:

cp .env.example .env.local

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# LaunchDarkly feature flags (server-side)
LAUNCHDARKLY_SDK_KEY=sdk-...

# Optional: LaunchDarkly client-side id (for future client SDK usage)
NEXT_PUBLIC_LAUNCHDARKLY_CLIENT_SIDE_ID=...

# Database (Neon/PostgreSQL)
DATABASE_URL=postgresql://user:password@host:port/database

# Entry content encryption (base64-encoded 32-byte key)
ENTRY_CONTENT_ENCRYPTION_KEY=replace-with-openssl-rand-base64-32

# App URL (used in invite links)
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Invite Email Provider (optional)
# Resend is auto-detected when RESEND_API_KEY and RESEND_FROM_EMAIL are set.
# Optionally set INVITE_EMAIL_PROVIDER=resend explicitly, or INVITE_EMAIL_PROVIDER=none to disable email sending.
INVITE_EMAIL_PROVIDER=resend
RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=SharedJournal <[email protected]>

# Support payments (Stripe)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Content Moderation Quickstart

SharedJournal can moderate entry and reflection content before writing to the database.

Add these variables to .env.local to enable moderation locally:

# Content moderation
CONTENT_MODERATION_ENABLED=true
CONTENT_MODERATION_PROVIDER=openai
CONTENT_MODERATION_API_KEY=sk-...

# Behavior when provider is unavailable:
# open   -> allow writes (default)
# closed -> block writes and return retry message
CONTENT_MODERATION_FAIL_MODE=open

Behavior summary:

• CONTENT_MODERATION_ENABLED must be exactly true to enforce moderation.
• With CONTENT_MODERATION_FAIL_MODE=open, provider errors allow writes.
• With CONTENT_MODERATION_FAIL_MODE=closed, provider errors block writes with a generic retry error.
• Moderation runs before encryption and persistence for entry creation and reflection creation.

For full implementation details, see docs/content-moderation-implementation.md.

Stripe Integration (Support Payments)

SharedJournal supports optional one-time "buy me a coffee" style contributions via Stripe Checkout.

What is implemented

• Support page: /support
• Checkout creation: server action in src/app/support/actions.ts
• Webhook endpoint: /api/webhooks/stripe
• Success page: /support/success
• Payment records stored in support_payments

Required Stripe events

Configure these events for your webhook endpoint:

• checkout.session.completed
• checkout.session.async_payment_succeeded
• checkout.session.async_payment_failed
• checkout.session.expired

Local development setup

1. Ensure your Stripe test key is configured:

• STRIPE_SECRET_KEY=sk_test_...

2. Start the app:

npm run dev

3. In a separate terminal, start Stripe CLI forwarding:

stripe listen --events checkout.session.completed,checkout.session.async_payment_succeeded,checkout.session.async_payment_failed,checkout.session.expired --forward-to http://localhost:3000/api/webhooks/stripe

4. Copy the webhook signing secret printed by Stripe CLI (whsec_...) and set:

• STRIPE_WEBHOOK_SECRET=whsec_...

Notes:

• For local testing with Stripe CLI, you do not need to manually create a webhook endpoint in the Stripe Dashboard.
• Use Stripe test cards in Checkout, for example 4242 4242 4242 4242.

Production / Preview setup

For deployed environments (Vercel preview or production):

1. Create a Stripe webhook endpoint in Dashboard for each environment URL:

• https://<your-domain>/api/webhooks/stripe

2. Subscribe it to the required events listed above.
3. Use that endpoint's signing secret as STRIPE_WEBHOOK_SECRET in that environment.

Important:

• Webhook secrets are endpoint-specific.
• Local Stripe CLI whsec_... is different from production/preview dashboard endpoint secrets.
• Keep test and live credentials separated (sk_test_... vs sk_live_...).

Migration requirement

Stripe support payments require the support_payments table migration. Run:

npm run db:migrate

before testing checkout.

LaunchDarkly Feature Flags

SharedJournal now includes a server-side LaunchDarkly helper at src/lib/launchdarkly/server-client.ts.

Basic usage in a Server Component or Server Action:

import {
  createLaunchDarklyContext,
  getLaunchDarklyVariation,
} from '@/lib/launchdarkly/server-client'

const context = createLaunchDarklyContext({
  key: appUser.id,
  name: appUser.displayName,
})

const isNewExperienceEnabled = await getLaunchDarklyVariation({
  flagKey: 'new-experience',
  context,
  fallback: false,
})

Notes:

• Feature-flag evaluation should happen in Server Components / Server Actions.
• LAUNCHDARKLY_SDK_KEY must be set in your environment for the helper to initialize.

Clerk Authentication

1. Create a Clerk account at clerk.com
2. Get your API keys from the Clerk Dashboard
3. Add your keys to .env.local

This is the beginning of the README. Read the rest at the original. Read the full README ↗