docs: add Getting Started section to README#71
docs: add Getting Started section to README#71p6l-richard wants to merge 4 commits intojoschan21:mainfrom
Conversation
Help new contributors get up and running with prerequisites (Neon database setup) and step-by-step instructions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
@p6l-richard is attempting to deploy a commit to the joschan21's projects Team on Vercel. A member of the Team first needs to authorize it. |
📝 WalkthroughWalkthroughREADME.md replaced its top section with a full project landing and expanded Getting Started/onboarding: adds centered logo/title/badges, Prerequisites (DATABASE_URL, Neon/Postgres, NEXT_PUBLIC_POSTHOG_KEY), step-by-step clone/configure/install/push-db/run-dev instructions, and a new Public Roadmap with expanded priority and bug lists. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README.md`:
- Line 5: Replace the incorrect phrase "help others getting started" with the
correct infinitive form "help others get started" in the README text (the line
containing "**Note:** This is a WIP and not comprehensive. Please contribute an
improvement if you want to help others getting started or us to offer a better
onboarding experience."); update that sentence accordingly and commit the
change.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README.md`:
- Around line 59-63: Update the README's "Configure secrets" section to
enumerate required vs optional environment variables by reading .env.example and
listing (at minimum) the variables required for a basic local run (e.g.,
DATABASE_URL, NEXTAUTH_URL/SECRET or auth-related vars, PORT if used, and any DB
migration flags) and grouping feature-specific/optional vars (OpenRouter,
Upstash, QStash, Twitter, Google, Firecrawl, AWS, Stripe, PostHog, Marble, etc.)
that are only needed when using those integrations; modify the text around the
existing "cp .env.example .env" and the "Prerequisites" reference to include a
short checklist of required keys and a pointer to the full .env.example for
optional keys so users can clearly see which variables are mandatory to avoid
setup failures.
| 2. **Configure secrets.** Set environment variables: | ||
| ```bash | ||
| cp .env.example .env | ||
| ``` | ||
| Then fill in the keys obtained from [Prerequisites](#prerequisites) (at minimum `DATABASE_URL`). |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# List environment variables in .env.example to align README prerequisites.
if [ -f .env.example ]; then
echo "Vars in .env.example:"
rg -n '^[A-Z0-9_]+=' .env.example
else
echo ".env.example not found"
exit 1
fiRepository: joschan21/contentport
Length of output: 1038
🏁 Script executed:
# Read the README to see the current documentation at lines 59-63 and surrounding context
if [ -f README.md ]; then
echo "=== README.md lines 55-70 (context) ==="
sed -n '55,70p' README.md
else
echo "README.md not found"
fiRepository: joschan21/contentport
Length of output: 538
Document all required environment variables in README.
The .env.example contains 36+ variables across integrations (OpenRouter, Upstash, QStash, Twitter, Google, Firecrawl, AWS, Stripe, PostHog, Marble, etc.), but README only explicitly mentions DATABASE_URL. Specify which variables are required for basic setup versus optional for specific features to prevent setup failures.
🤖 Prompt for AI Agents
In `@README.md` around lines 59 - 63, Update the README's "Configure secrets"
section to enumerate required vs optional environment variables by reading
.env.example and listing (at minimum) the variables required for a basic local
run (e.g., DATABASE_URL, NEXTAUTH_URL/SECRET or auth-related vars, PORT if used,
and any DB migration flags) and grouping feature-specific/optional vars
(OpenRouter, Upstash, QStash, Twitter, Google, Firecrawl, AWS, Stripe, PostHog,
Marble, etc.) that are only needed when using those integrations; modify the
text around the existing "cp .env.example .env" and the "Prerequisites"
reference to include a short checklist of required keys and a pointer to the
full .env.example for optional keys so users can clearly see which variables are
mandatory to avoid setup failures.
There was a problem hiding this comment.
This getting started is a "WIP" as noted in the text and prompts other to contribute to it if something's missing.
This is a good example but the author of this PR didn't event ge tto test all env vars and therefore doesn't know which ones are required to run the development server.
This is important.
However, I did list this as an "Open Question" in the PR description suggesting a library. I believe it's up to @joschan21 & @jommerkatz to decide (1) the DX and (2) the appropriate tooling for this.
Thanks for pointing this out though, I hope this discussion adds value.
There was a problem hiding this comment.
Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!
| @@ -1,5 +1,81 @@ | |||
| <!-- PROJECT LOGO --> | |||
There was a problem hiding this comment.
lines 1-36 are basically just a visual touch up, preview is in the Demo section of the PR description
|
|
||
| ## Getting Started | ||
|
|
||
| > **Note:** This is a WIP and not comprehensive. Please contribute an improvement if you want to help others get started or us to offer a better onboarding experience. |
There was a problem hiding this comment.
I thought it would be nice to get others to contribute if they want. Every bit helps!
| ### Prerequisites | ||
|
|
||
| - **`DATABASE_URL`** — A serverless Postgres database. This project uses Drizzle with the PostgreSQL dialect. | ||
| <a href="https://console.neon.tech/signup"><img src="https://img.shields.io/badge/Sign%20up-Neon%20Database-00e599?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyeiIvPjwvc3ZnPg==" alt="Sign up for Neon" /></a> |
There was a problem hiding this comment.
Unsure if this repo should be opinionated or advertise the database provider.
At the very least, it should mention a serverless postgres provider though, which I mention on line 46 since drizzle isn't DBMSs ( database management systems) agnostic and exposes different methods for mysql & postgres.
There was a problem hiding this comment.
This is how the a button looks like. It looks nice but it's also mentioning an opinion about a provider of choice.
Move public roadmap under its own section, increment heading levels for roadmap content, and simplify the top-level title. Add PostHog as a prerequisite for analytics. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
p6l-richard
left a comment
p6l-richard
left a comment
There was a problem hiding this comment.
- Pushed a commit based on a review from coderabbit
- reviewed the PR, added comments where relevant
- Spotted a layout issue with the markdown, adjusted this
- Added
Posthogas the next env var - Documented all points inside the PR body under the
Open Questions&Testingsections
This is PR is now ready for review
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@README.md`:
- Line 3: Update the broken GitHub links in README.md that currently point to
"https://github.com/contentport" so they reference the correct repository path
"https://github.com/joschan21/contentport"; locate occurrences such as the
anchor tag <a href="https://github.com/contentport"> and any other similar links
(noted also around the other occurrences mentioned) and replace them with the
full joschan21/contentport URL to prevent 404s.
- Line 66: Update the README line that says "(at minimum `DATABASE_URL`)" to
reflect the actual prerequisites by listing both required keys (`DATABASE_URL`
and `NEXT_PUBLIC_POSTHOG_KEY`) so the minimum requirements match the
Prerequisites section; locate the sentence in README.md and change the
parenthetical to include `NEXT_PUBLIC_POSTHOG_KEY` (or alternatively adjust the
Prerequisites section if you intend a different minimum), ensuring the two
sections are consistent.
- Around line 44-52: The README's Prerequisites section has two issues: the Neon
CLI example `neonctl databases create --name contentport` is incomplete and
should show the required --project-id option (e.g., `--project-id
<your-project-id>`) or a note about when it’s required; and the README only
documents DATABASE_URL and NEXT_PUBLIC_POSTHOG_KEY while the repository’s
.env.example contains many other variables (OpenRouter, Upstash Redis/Vector,
QStash, Twitter API keys, Better Auth, Firecrawl, AWS, Stripe, Marble CMS,
etc.), so update the Prerequisites to (1) fix the neonctl example to include
--project-id or explain when it’s needed, and (2) add a short categorized list
marking each .env.example variable as required or optional with one-line setup
guidance or links for each (referencing DATABASE_URL, NEXT_PUBLIC_POSTHOG_KEY
and the other .env.example variable names) so developers know how to obtain and
configure them.
🧹 Nitpick comments (2)
README.md (2)
38-38: Consider title casing consistency.The section title uses lowercase "contentport" while the main project title uses "Contentport" (line 7). Consider using consistent casing throughout the document.
✨ Optional consistency fix
-# contentport +# Contentport
82-82: Update the roadmap timestamp.The roadmap shows "last updated: 29th Nov 2025", but it's now February 2026. Consider updating this timestamp to reflect the current state or remove it if not actively maintained.
| # **contentport — public roadmap (last updated: 29th Nov 2025)** | ||
| <!-- PROJECT LOGO --> | ||
| <p align="center"> | ||
| <a href="https://github.com/contentport"> |
There was a problem hiding this comment.
Fix repository references to match actual GitHub path.
The repository links point to the contentport organization, but the actual repository is joschan21/contentport (as shown in the clone commands at lines 58 and 60). This will cause 404 errors when users click these links.
🔗 Proposed fix for repository links
- <a href="https://github.com/contentport">
+ <a href="https://github.com/joschan21/contentport">- <a href="https://github.com/contentport/issues">Issues</a>
+ <a href="https://github.com/joschan21/contentport/issues">Issues</a>- <a href="https://github.com/contentport/stargazers"><img src="https://img.shields.io/github/stars/contentport" alt="Github Stars"></a>
- <a href="https://github.com/contentport/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
+ <a href="https://github.com/joschan21/contentport/stargazers"><img src="https://img.shields.io/github/stars/joschan21/contentport" alt="Github Stars"></a>
+ <a href="https://github.com/joschan21/contentport/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>Also applies to: 19-19, 32-32
🤖 Prompt for AI Agents
In `@README.md` at line 3, Update the broken GitHub links in README.md that
currently point to "https://github.com/contentport" so they reference the
correct repository path "https://github.com/joschan21/contentport"; locate
occurrences such as the anchor tag <a href="https://github.com/contentport"> and
any other similar links (noted also around the other occurrences mentioned) and
replace them with the full joschan21/contentport URL to prevent 404s.
| ### Prerequisites | ||
|
|
||
| - **`DATABASE_URL`** — A serverless Postgres database. This project uses Drizzle with the PostgreSQL dialect. | ||
| <a href="https://console.neon.tech/signup"><img src="https://img.shields.io/badge/Sign%20up-Neon%20Database-00e599?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyeiIvPjwvc3ZnPg==" alt="Sign up for Neon" /></a> | ||
|
|
||
| Or, if you prefer the CLI: `neonctl databases create --name contentport` ([Neon CLI docs](https://neon.com/docs/reference/cli-databases)) | ||
|
|
||
| - **`NEXT_PUBLIC_POSTHOG_KEY`** — A PostHog project API key for analytics. | ||
| <a href="https://us.posthog.com/signup"><img src="https://img.shields.io/badge/Sign%20up-PostHog-1d4aff?style=for-the-badge&logo=posthog&logoColor=white" alt="Sign up for PostHog" /></a> |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -name ".env*" -o -name "README.md" | head -20Repository: joschan21/contentport
Length of output: 122
🏁 Script executed:
if [ -f .env.example ]; then
echo "=== Variables in .env.example ==="
cat .env.example
else
echo ".env.example not found, searching for environment config files..."
fd -H "env" -t f | grep -E "\.(env|example)" | head -20
fiRepository: joschan21/contentport
Length of output: 1106
🏁 Script executed:
# Verify the base64 SVG badge decodes correctly
echo "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyeiIvPjwvc3ZnPg==" | base64 -d | head -1Repository: joschan21/contentport
Length of output: 222
🌐 Web query:
Neon CLI neonctl databases create command syntax documentation
💡 Result:
neonctl databases create (Neon CLI) syntax
Neon’s docs show the command as neon ... (the CLI has an alias neonctl). [2]
neon databases create [options]
# (equivalently: neonctl databases create [options])Options (for create): [1]
--name <database_name>(required)--branch <branch_id_or_name>--owner-name <role_name>--project-id <project_id>(required only if your account has >1 project)--context-file <path>
Example: [1]
neon databases create --name mynewdb --owner-name johnSources: [1] Neon Docs — “Neon CLI commands — databases” (create usage/options) • [2] Neon Docs — “Neon CLI” (shows neon with alias neonctl)
🏁 Script executed:
# Verify the Neon badge URL is valid
curl -s -o /dev/null -w "Neon badge status: %{http_code}\n" "https://img.shields.io/badge/Sign%20up-Neon%20Database-00e599?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyeiIvPjwvc3ZnPg=="
# Verify the PostHog badge URL is valid
curl -s -o /dev/null -w "PostHog badge status: %{http_code}\n" "https://img.shields.io/badge/Sign%20up-PostHog-1d4aff?style=for-the-badge&logo=posthog&logoColor=white"
# Verify Neon signup URL is valid
curl -s -o /dev/null -w "Neon signup status: %{http_code}\n" "https://console.neon.tech/signup"
# Verify PostHog signup URL is valid
curl -s -o /dev/null -w "PostHog signup status: %{http_code}\n" "https://us.posthog.com/signup"Repository: joschan21/contentport
Length of output: 164
🏁 Script executed:
# Search the codebase to understand which env vars are required vs optional
echo "=== Checking which env vars are actually used in code ==="
rg 'process\.env\.' --no-heading -o | sed 's/.*process\.env\.//' | sed 's/[^A-Z0-9_].*//' | sort -u | head -50Repository: joschan21/contentport
Length of output: 123
🏁 Script executed:
# Try different patterns to find env var usage
echo "=== Searching for environment variable references ==="
rg 'DATABASE_URL|OPENROUTER|UPSTASH|QSTASH|TWITTER|GOOGLE|STRIPE|FIRECRAWL|AWS_|MARBLE|BETTER_AUTH|POSTHOG' --type ts --type tsx --type js --type jsx -c | head -20Repository: joschan21/contentport
Length of output: 163
🏁 Script executed:
# Check if there's any setup/initialization documentation
ls -la | head -20
cat package.json | grep -A 10 '"scripts"'Repository: joschan21/contentport
Length of output: 1638
🏁 Script executed:
# Look for configuration files that document env vars
fd -t f -e "config" -e "constants" -e "setup" | head -20Repository: joschan21/contentport
Length of output: 47
Fix incomplete Neon CLI command and document missing environment variables.
The badges render correctly, but two issues need addressing:
-
Neon CLI command is incomplete (line 49): The example
neonctl databases create --name contentportomits the--project-idparameter, which is required when a user has multiple projects in their Neon account. Consider updating to:neonctl databases create --name contentport --project-id <your-project-id>or documenting this requirement more clearly. -
35 of 37 environment variables in
.env.exampleare undocumented: OnlyDATABASE_URLandNEXT_PUBLIC_POSTHOG_KEYare mentioned in Prerequisites. The remaining variables (OpenRouter, Upstash Redis/Vector, QStash, Twitter API keys, Better Auth, Firecrawl, AWS, Stripe, and Marble CMS) lack any setup guidance, which will likely cause setup failures for developers. Categorize these as required or optional and provide brief setup instructions for each.
🤖 Prompt for AI Agents
In `@README.md` around lines 44 - 52, The README's Prerequisites section has two
issues: the Neon CLI example `neonctl databases create --name contentport` is
incomplete and should show the required --project-id option (e.g., `--project-id
<your-project-id>`) or a note about when it’s required; and the README only
documents DATABASE_URL and NEXT_PUBLIC_POSTHOG_KEY while the repository’s
.env.example contains many other variables (OpenRouter, Upstash Redis/Vector,
QStash, Twitter API keys, Better Auth, Firecrawl, AWS, Stripe, Marble CMS,
etc.), so update the Prerequisites to (1) fix the neonctl example to include
--project-id or explain when it’s needed, and (2) add a short categorized list
marking each .env.example variable as required or optional with one-line setup
guidance or links for each (referencing DATABASE_URL, NEXT_PUBLIC_POSTHOG_KEY
and the other .env.example variable names) so developers know how to obtain and
configure them.
| ```bash | ||
| cp .env.example .env | ||
| ``` | ||
| Then fill in the keys obtained from [Prerequisites](#prerequisites) (at minimum `DATABASE_URL`). |
There was a problem hiding this comment.
Update minimum requirements to match Prerequisites.
Line 66 states "(at minimum DATABASE_URL)", but the Prerequisites section lists both DATABASE_URL and NEXT_PUBLIC_POSTHOG_KEY as required. This inconsistency may confuse users about what's truly required.
📝 Proposed fix
- Then fill in the keys obtained from [Prerequisites](`#prerequisites`) (at minimum `DATABASE_URL`).
+ Then fill in the keys obtained from [Prerequisites](`#prerequisites`) (at minimum `DATABASE_URL` and `NEXT_PUBLIC_POSTHOG_KEY`).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Then fill in the keys obtained from [Prerequisites](#prerequisites) (at minimum `DATABASE_URL`). | |
| Then fill in the keys obtained from [Prerequisites](`#prerequisites`) (at minimum `DATABASE_URL` and `NEXT_PUBLIC_POSTHOG_KEY`). |
🤖 Prompt for AI Agents
In `@README.md` at line 66, Update the README line that says "(at minimum
`DATABASE_URL`)" to reflect the actual prerequisites by listing both required
keys (`DATABASE_URL` and `NEXT_PUBLIC_POSTHOG_KEY`) so the minimum requirements
match the Prerequisites section; locate the sentence in README.md and change the
parenthetical to include `NEXT_PUBLIC_POSTHOG_KEY` (or alternatively adjust the
Prerequisites section if you intend a different minimum), ensuring the two
sections are consistent.
1 participant
Summary
.env, install, push schema, run dev server)Why this changed
I wanted to get set up and running and followed the steps that I'm contributing here and saw the first error when running
bun i && bun devwas about a missingDATABASE_URL.Out of scope
The real issue is that I was stuck with procuring the OAuth client secrets for social cross-posting. This is out of scope for this PR though, I shared some thoughts on Twitter with people that I had to think about but I'm not the right author for this discussion.
Demo
Header
Getting Started
Open questions
envvariable checks to display a useful error message to users/agents when whenDATABASE_URLis missing (e.g. https://github.com/t3-oss/t3-env). Maybe the database setup instructions from the Prerequisites should be showed then, unsure.To test
Credits
Shoutout to the one and only @PeerRich for creating a polished and beautiful readme header for calcom.
🤖 Generated with Claude Code
🦁 Initiated and editorially hand-crafted by Richard in Berlin.
Summary by CodeRabbit