Skip to content

faq.mdx

Latest commit

 

History

History
498 lines (311 loc) · 30.1 KB

faq.mdx

File metadata and controls

498 lines (311 loc) · 30.1 KB
Raw

FAQ

Getting Started

Do I need a Reddit API key, client ID, or client secret to build with Devvit?

No. If you're building a Devvit app, you don't need to create a traditional Reddit app at reddit.com/prefs/apps or manage API keys yourself.

Instead, start from the App quickstart or create a project at developers.reddit.com/new. During setup, you sign in with your Reddit account and connect it to Reddit developers. Devvit handles authentication for your app.

To read or write Reddit content from a Devvit app, enable the Reddit capability described in the Reddit API Overview.

:::note If you're building an external script, bot, or website outside Devvit, that's a different authentication flow from the one documented here. :::

Where do I start building a Devvit app?

The fastest path is the App quickstart, which walks you through creating a project, connecting your Reddit account, and starting a playtest environment.

If you already know what you want to build, you can also start with:

How do I log in, and how do I know I am authenticated?

Use the CLI to sign in with your Reddit account:

npx devvit login

To confirm which account is currently authenticated, run:

npx devvit whoami

After login, Devvit stores your access token locally at ~/.devvit/token and refreshes it automatically while you use the CLI.

For command details, see the devvit login and devvit whoami sections of the CLI reference.

Building and Testing

Can I test locally without uploading to Reddit?

Not completely. Devvit apps run against Reddit, so the normal development flow uses a playtest subreddit rather than a purely local setup.

The quickstart uses npm run dev, which starts a Devvit playtest session for you. If you need more control over that flow, see Playtest.

If you're wondering why a purely local setup isn't enough, the quickstart calls this out directly: backend calls don't work when you test the app only locally.

Why does npm run dev, playtest, upload, or install fail?

Most development errors fall into a few buckets:

  • Authentication: make sure you're logged in with npx devvit login, then verify the current account with npx devvit whoami.
  • Build output mismatch: if Devvit can't find config.server.entry, check that your built server file matches the path in devvit.json, and that your server build outputs a CommonJS bundle. The best references are Devvit configuration and Vite.
  • Config validation: if devvit.json complains about invalid fields, extra properties, or settings shapes, validate it against the schema and configuration rules in Devvit configuration.
  • Fetch or domain errors: if fetch is disabled or a domain is rejected, configure permissions.http correctly and review the rules in HTTP fetch.
  • Runtime failures during playtest or install: use Playtest and Logs and Debugging together so you can see the failing endpoint or trigger.

One other common gotcha: Devvit projects use vite build --watch rather than a normal vite dev server. The Vite guide explains the expected setup.

How do I update the Devvit CLI?

Prefer updating the project-local CLI dependency instead of relying on a global install. Update devvit in your project, then run npx devvit update app so your @devvit packages match the CLI.

For the current commands and workflow, see Devvit CLI and the update notes in Changelog.

How do I update my app version?

Updating the CLI and publishing a new app version are separate steps. Your app version changes when you publish: npx devvit publish creates the next launch version, and you can control that with --bump or --version as described in Launch your app.

After that, the subreddit still needs to be on the version you want installed. Publishing a new version doesn't automatically update every subreddit. Use devvit install or open your app in the App Directory and, under Installed in communities, use the blue Update button for the subreddit that's out of date.

I published and it says a new Devvit version is available. Do I need to upgrade?

Not necessarily. If you're within 2–3 versions of the current Devvit release, your app will continue working as-is. The version notice is informational — it doesn't mean your app is broken or blocked from publishing.

Staying reasonably current is good practice, though. It gets you access to the latest fixes and capabilities. When you're ready, run npx devvit update app to bring your project's @devvit packages in line with the latest CLI, then test in playtest before publishing the update.

For upgrade steps, see Devvit CLI and the Changelog.

What is the difference between npx devvit upload and npx devvit publish?

Use npx devvit upload when you want a private uploaded build for yourself, and use npx devvit publish when you're ready to submit a version for launch review. In practice, playtest is still the normal dev loop, upload is useful for a private installable build, and publish is the launch step documented in Launch your app.

For command syntax, see Devvit CLI. For the review and launch flow, see Launch your app.

What should I do after playtest when I am ready to launch?

Before launch, make sure the app is stable across mobile and web, test with multiple accounts, and add an installer-friendly README.md. Then follow the publish flow in Launch your app.

If you're just ending a playtest session, remember that the latest playtest install remains in place until you change installs. Playtest and devvit install cover that handoff.

How long does it take to get my app published?

Most app versions are reviewed within 1–2 business days. New apps or versions that include higher-risk features may take longer. Features that commonly extend review time:

  • Payments: apps using the payments capability go through additional policy review.
  • runAs: 'USER': user action permissions require explicit approval as part of the review.
  • External fetch domains: new domain requests are reviewed separately and can add time (see HTTP Fetch).

To keep review moving:

  • Make sure your README.md is clear, accurate, and up to date.
  • Ensure your app complies with the Devvit Rules.
  • If your app uses fetch domains, document them in a "Fetch Domains" section of your README.

If you haven't heard back after a week, reach out in the Devvit Discord or via r/Devvit Modmail. For the full publish flow, see Launch your app.

How do I install my app on another subreddit?

If you moderate the destination subreddit, use devvit install to install a specific app or version on that community. That's the direct CLI path when you want to move beyond the playtest subreddit or test on another subreddit you control.

If the goal is broader distribution, follow Launch your app so moderators can install the approved app in the appropriate way for its visibility level.

What is the difference between unlisted and public apps?

Published apps are unlisted by default. That's usually the right fit for games and single-community tools. If you want your app to appear in the App Directory so any moderator can install it, use npx devvit publish --public and follow the listing guidance in Launch your app.

Public apps should look launch-ready: the launch docs call for a detailed installer-facing README.md, and game launch guidance expects a custom launch or first screen rather than a rough default experience.

App Features

What is an interactive post in Devvit?

An interactive post is a Reddit post created for an app experience rather than a plain text-only post. That means creating the post with reddit.submitCustomPost() and defining how it launches through entry points, launch screens, and optional postData. See Interactive posts overview and Creating a custom post.

Why is my post just text instead of an interactive app post?

If you call submitPost() with normal text, you're creating a regular Reddit post. To create an interactive app post, use submitCustomPost() and point it at your configured entry point instead. The Interactive posts overview is the clearest starting point for that distinction.

What is Devvit Web?

Devvit Web is the current client/server app model for building Devvit apps with standard web tools like React, Phaser, or Three.js. It's a normal web app plus server endpoints plus devvit.json configuration, with Reddit capabilities split between client APIs, server APIs, and config. See Devvit Web overview.

I got a notice that Blocks is deprecated. What do I need to do?

Blocks is being replaced by Devvit Web. The path depends on how your app is built, but here's what to check first:

  • devvit.yaml: If your project still has a devvit.yaml, replace it with a devvit.json. See Migrating Blocks/Mod Tools to Devvit Web for the updated config format and steps.
  • Devvit.addCustomPostType(): This is the core Blocks API and is deprecated. Move your post rendering to a client entry in devvit.json, backed by a standard HTML, React, or other web app.
  • submitCustomPost() with preview: The preview field (used to render a Blocks component as the post preview) is no longer the right pattern. Use post.entrypoints in devvit.json to define your inline and expanded views as HTML entry points instead.
  • useWebView: If your app launched a web view from inside Blocks, migrate to Devvit Web. See Migrating from useWebView to Devvit Web.

If your app uses only Blocks without a web view, Migrating Blocks/Mod Tools to Devvit Web is the quickest path. If your app has a web view, start with Migrating from useWebView to Devvit Web.

Where do I customize the first screen or launch screen?

For current Devvit Web apps, customize the first screen through your post.entrypoints in devvit.json and the HTML, CSS, and client code for those entry files. The main references are Launch overview, View modes and entry points, and Launch screen customization.

Should I use the legacy splash field or HTML launch entry points?

:::warning Deprecation notice: The splash parameter in submitCustomPost() and Blocks-based launch screens will be deprecated in June. Migrate to HTML-based entry points before then. :::

Use HTML launch entry points for all new and existing work. The older splash parameter is deprecated in favor of entrypoint-based launch screens and entry selection in submitCustomPost(). If you're updating an older app, start with Migrating from Splash Screens.

How do I handle scrolling and touch gestures in inline vs expanded mode?

Treat inline and expanded mode differently. Inline should avoid scroll traps and heavy gesture hijacking so users can still scroll past the post, while expanded is the right place for richer touch interaction and more space.

There's no single canonical viewport size for all devices. Design responsively, test in UI Simulator, and use the current launch-mode docs for inline vs expanded behavior in View modes and entry points and Launch screen customization.

How do I add images that ship with my app?

Put static images in your client dist/ directory when they should ship with the app version, such as logos, backgrounds, or other bundled art. Reference them directly from your web client (for example via <img src="/logo.png" />).

How do user image uploads work in Devvit?

The simplest path is a form field with type: 'image', which returns a Reddit-hosted image URL when the user submits it. For custom flows like screenshots or generated images, send the data to your server and upload it with Media uploads.

See Forms and Media uploads for the supported formats and size limits.

What image URLs can I use in a Devvit app?

The documented display paths are bundled client assets, Reddit-hosted URLs, and SVG data URLs, depending on the UI surface. If your source image lives somewhere else on the web, don't assume you can hotlink it directly into the UI. Upload it first so Reddit hosts the image, then use the returned URL. See Media uploads.

What is postData, and when should I use it instead of Redis?

Use postData for small shared JSON attached to a single post, like lightweight game state or configuration that all viewers need to read. The docs cap it at 2 KB per post and recommend Redis for larger or more persistent data patterns.

How do I access or update postData?

Set postData when creating the post, then read it from context.postData on either the client or server side. To update it later, fetch the post and call setPostData(). The important gotcha is that setPostData() replaces the whole object, so merge existing fields first. See Post data.

How do I build a leaderboard with Redis?

The standard Devvit pattern is to build leaderboards with Redis sorted sets. Use Redis for score storage and ranking, use Scheduler for daily or periodic resets, and prefer realtime updates over constant polling when you need a live leaderboard.

Redis is the right storage layer, but the exact schema depends on whether you need daily, weekly, or all-time rankings. Redis is the best starting point.

Can a menu action create a new post?

Yes. Define the menu item in devvit.json, implement the server endpoint it calls, and create the post from that route. The pattern is documented across Menu actions and Interactive posts overview.

How do I automate daily or scheduled game posts?

Use Scheduler for cron-style recurring jobs or one-off jobs declared in devvit.json, then handle the matching /internal/... endpoint in your server code. The scheduler docs explain the plumbing; the post creation step still uses the normal Reddit APIs like submitCustomPost().

How do I post or comment as the user instead of the app?

Add the required permissions.reddit.asUser entries in devvit.json, then call the supported Reddit APIs with runAs: 'USER'. The main doc for this is User Actions, which also explains the review requirements, explicit opt-in rules, and userGeneratedContent expectations.

Why does runAs: 'USER' still post as the app during playtest?

Before the app version is approved, user actions aren't enabled for everyone. During playtest or other unapproved versions, runAs: 'USER' falls back to the app account for most users, while actions taken by the app owner are attributed to the owner's username. After publishing and approval, it operates on behalf of the user for all users. See User Actions.

How do I set or update user flair and post flair?

Devvit supports both user flair and post flair through the Reddit API client.

  • For a new post, use the submit options documented in CommonSubmitPostOptions, including flairId or flairText.
  • For an existing post, use the flair methods on RedditAPIClient, such as setPostFlair() and removePostFlair().
  • For a user, use setUserFlair(), removeUserFlair(), or setUserFlairBatch() on the same client.

If you're reading flair back from a post, note that post flair and author flair are different fields. The Post model exposes flair for the post and authorFlair for the post author.

If you need to react to flair changes, Devvit documents an onPostFlairUpdate trigger for post flair changes. Also note that the Devvit test tool doesn't yet support the Flair service.

How do I get a user's username or snoovatar?

If you only need the current user's name, prefer getCurrentUsername() over fetching the full user object.

If you need more profile information, use getCurrentUser() from the Reddit API client. To get a snoovatar URL, use reddit.getSnoovatarUrl(username) or user.getSnoovatarUrl() on the User model.

Some handlers also expose experimental identity fields like username and snoovatar on BaseContext, but the Reddit client methods are the clearest documented path.

How do I handle external links in Devvit?

Use Devvit navigation APIs to open links rather than treating this like external fetch. For app navigation, see Navigation, which covers navigateTo and the confirmation flow for external URLs.

If you actually need remote data or remote media, that's a different path: use HTTP fetch for approved server-side fetches, and Media uploads when you need a Reddit-hosted media URL.

How do I update my app profile settings?

App profile settings let you control how your app appears on Reddit via a combination of configuration in devvit.json and fields in the Developer Portal.

Avatar (profile icon) To update your avatar:

  1. In your devvit.json, set the marketingAssets.icon field to the path to your icon from the project root.
  2. When you publish your app and it is approved, this icon is uploaded to your app’s Reddit profile.
  3. To change the icon later, update marketingAssets.icon in devvit.json and submit the app for a new review.
  4. Only image avatars are supported at this time. Snoovatars are not supported for apps.

You can also edit the display name, about description, and mature flag (18+) fields in the Developer Portal under Developer Settings. Updates will appear in the Developer Portal and on the app's Reddit profile.

Limits and Policies

What are the main storage, payload, and rate limits?

There's no single limits page today, but these are the most commonly referenced numbers in the docs:

  • Redis: 500 MB max storage per installation, 5 MB max request size, and 40,000 max commands per second.
  • Devvit Web: 30 second max request time, 4 MB max payload size, and 10 MB max response size.
  • Post data: 2 KB per post.
  • Settings and secrets: 2 KB per setting value.
  • Realtime: 1 MB maximum message payload and 100 messages per second per installation.
  • Scheduler: up to 10 live recurring actions per installation, plus runJob() limits documented on that page.

If you need data to survive app updates, don't rely on browser localStorage. The Devvit Web overview recommends Redis for persistent storage across versions.

How long does it take to get my domain approved?

Domain requests are reviewed separately from app publishing and can take up to 4 business days. If your app was approved but a requested fetch domain wasn't yet granted, the domain review may still be in progress.

To make approval go smoothly:

  • Use exact hostnames only — no wildcards (*.example.com), no protocols (https://), and no paths (api.example.com/webhooks).
  • Add a "Fetch Domains" section to your README.md listing each domain and explaining why you need it. The expected format is documented in HTTP Fetch.
  • Include links to your Terms and Conditions and Privacy Policy in your app details form.

Before submitting, check the global fetch allowlist — if your domain is already listed there, no separate request is needed. Personal domains (e.g., personaldomain.com) aren't approved.

What screen sizes should I design for?

There's no single published pixel size for every device or view mode. Build responsive layouts and test them across the views supported by the UI Simulator: mobile, desktop, and fullscreen.

Inline and expanded mode behave differently: expanded is the larger experience, with more room for rich interaction, while inline should stay lightweight and feed-friendly.

Start with mobile-first assumptions and validate in the simulator before hard-coding dimensions. The best references are View modes and entry points, Launch screen customization, and UI Simulator.

Can I build NSFW games or apps with Devvit?

There's no separate NSFW platform guide in these docs, so the main source of truth is Devvit Rules plus Reddit's linked platform policies.

The rules explicitly require labels or age-gating before exposing users to graphic, sexually explicit, or otherwise mature content. Static assets and uploaded media are also subject to the same safety checks and policy review described in Media uploads.

If your app idea depends on adult content or NSFW communities, review those rules first and get clarification in the Devvit Discord before you ship.

Help and Next Steps

Where do I go for help if I am stuck?

For help from the Devvit team and community:

How do I uninstall or remove a Devvit app from a subreddit?

Use the CLI to inspect installs and uninstall from a subreddit. The current docs point to list installs and uninstall in Devvit CLI.

There's also a manual path in the App Directory. Open your app there, then either use Installed in communities to select a subreddit and choose Remove from community, or scroll to the bottom of the app page and use Archive if you want to archive the app itself.

Be careful: uninstalling from a subreddit can remove that installation's stored data and settings. See Mod resources for the current warning about uninstall data loss.

What is Devvit MCP and how do I set it up?

Devvit MCP is the bridge used by supported coding tools and agents to search Devvit docs and, in some setups, work with Devvit workflows from your editor. The setup docs live in Using AI Tools.

If you're configuring Cursor, VS Code Copilot, Claude Code, or Claude Desktop, start there instead of duplicating the JSON in this FAQ. Use the AI tools guide for the exact MCP config and supported tools.

What should I read next?