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

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗