Quickstart

The following quickstart shows you how to install the Devvit command line tool and use it to get an app running on a test subreddit.

Requirements

Make sure you have the following software installed:

• Node.js 14.17.0 or higher
• Node.js package manager: either npm or Yarn 1.x
• Git 2.28.0 or higher
• the latest version of Chrome or Firefox

What you'll learn

In this quickstart, you'll learn how to:

• Set up your development environment
• Create an app using a template
• Install an app on a subreddit
• View logging messages for your app
• Update your app

Before you begin

This guide assumes you have no Javascript or Node.js experience, but are familiar with basic coding principles and working from a command line.

Before you begin, you need:

1. A Reddit account that has been allowlisted for access to the Reddit Developer Platform (contact us if you don't have one yet).
2. A subreddit with full moderator permissions and fewer than 10 members. Your test subreddit can be any type: public, restricted, private, or Not Safe For Work (NSFW).
3. An editor for viewing and editing code (we recommend VS Code).

note

If you've never installed Node.js on your computer, please use the installation instructions below.

Set up your environment

Install Node.js

Click here for instructions on installing Node.js

You’re going to work with TypeScript. In order for Typescript to work with Devvit, you’ll need a working Node.js environment and then the Devvit command line interface. Node.js is an open-source server environment that makes it possible to develop and run Javascript apps anywhere. Node.js lets you import and use packages (code that other people have written) into your code.

Option 1: Use node version manager (nvm)

Install or update nvm to use as a handy command-line tool for managing multiple Node.js versions on your system. This will allow you to switch between different versions easily. If you to use a different node version manager, check out these suggestions from nmpjs.org.

For macOS or Linux:

1. Run the following command line in your terminal to install nvm.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

2. Close and re-open your terminal to have nvm available.

3. Install the latest version of Node.js.

nvm install node

For Windows:

1. Download and install nvm-windows by following the instructions in the repository.

2. Restart your terminal or command prompt.

3. Install the latest version of Node.js.

nvm install node

Option 2: Use Node.js installer from nodejs.org

1. Visit the official Node.js website to download the installer for your operating system (Windows, macOS, or Linux).
2. Run the installer and follow the prompts to install Node.js and npm (the package manager for Node.js).

note

If you install Node.js this way, you may experience permissions issues when trying to run Devvit, which is documented on NPM's website. Both NPM and us here at Reddit highly encourage you to use nvm if possible. If that's not possible, here are some tips on how to fix these permissions issues. For Windows users specifically, please use a node version manager.

Verify Node.js installation

Check that Node.js is installed correctly by running the following commands:

node --version
npm --version

You should see the version numbers for Node.js and npm as output.

Install Devvit

To download and install the Devvit CLI, run one of the following commands:

npm install -g devvit

-OR-

yarn global add devvit

note

If you see permission errors, please read npm's official guide . Yarn depends on the same configuration as npm.

Log in to Devvit

Use your Reddit username to log into Devvit. When you run the Devvit login, a Reddit authentication page will open in your browser (if the page doesn’t open automatically, you can use the link in the command line output).

The Devvit login will run until you follow the link and complete the authentication process.

Run:

devvit login

note

If you can't log in, make sure you are using a Reddit account that has been allowlisted for the Reddit Developer Platform.

To verify your authentication, run:

devvit whoami

The output will be similar to this:

Logged in as u/yourredditusername

Create an app

Now that your environment is set up, you’re ready to create an app! In this exercise, you’ll use the hello-world template to create a menu app that says "Hello World" when clicked.

To create a new directory with code for the app:

1. From the terminal, navigate to a directory where you'd like to store your code.
2. Enter the following command to create the app

devvit new --template hello-world

3. At the prompt, enter a name for your app and press the return key.

info

Remember that app names must be between 3 - 16 characters in length, all lowercase, can't start with numerals, and include only a-z, 0-9 or '-' (for example, my-hello-world).

Explore your app

You now have a full directory with your app name. There are several files and folders in this directory. You can ignore most files, but make note of src/main.ts. This contains the main code for your app.

my-simpler-project
├── devvit.yaml
├── package.json
├── src
│   └── main.ts         # <- the main code is here (ignore the rest for now)
├── tsconfig.json
├── yarn.lock

Upload your app

Next you’ll upload your app to the Community App Directory. Don’t worry, this is a private version that only you can see.

1. Navigate to the directory you just created (in our example, cd my-hello-world).
2. Run npm install to install relevant dependencies.
3. Run devvit upload.
4. At the prompt, confirm the creation of your app.
5. Add a description of your app that is at least 15 characters. You can always change your description later.
6. Indicate if your app is Not Safe For Work (NSFW). The default is "no", so you can hit enter for this step.
7. Make sure that you’re in the appropriate directory. In our example, you should be in the yourredditusername-hello-world directory.

my-simpler-project     # <- you should be here before uploading
├── devvit.yaml
├── package.json
├── src
│   └── main.ts
├── tsconfig.json
├── yarn.lock

7. Enter devvit upload.

You should see something like this:

Publishing new version "1.0.0.0" to Reddit...... Success!

note

When you upload a new app, an app account is automatically created just for your app.

Install your app

You can install your app on any subreddit that you moderate with full permissions. There are two ways to install an app on your subreddit: the Community App Directory or the Devvit CLI.

note

For the beta, you must create a test subreddit with fewer than 10 members for your personal testing. Contact us to allowlist larger subreddits on a case-by-case basis.

Use the Community App Directory

1. Navigate to My apps and find your app in the list.

2. Click on the entry for your app to open the app details page.

3. Click the Install button. You will see a list of subreddits you are allowed to use to install your app.

note

If the Install button is not active, you are not the moderator of an eligible subreddit. Try creating a new test subreddit with fewer than 10 members.

Use the Devvit CLI

You can use the CLI command devvit install <app-name> <subreddit> to install apps. From the CLI, enter:

devvit install your-app-name r/devvit_test

View your app

You're ready to use the app!

1. Navigate to reddit.com on your desktop web browser (Android and iOS support are coming soon!).
2. Go to the subreddit where you installed your app
3. Refresh the page (new apps may take a second to load)
4. Make sure there is at least one post.
5. Click the three dots on the bottom of the post. You'll see several robot icons with with associated actions at the bottom of the menu.

6. Click on any of the robot icons to create an informational toast message at the bottom of the screen.

Debug your app

You can stream log events from your installed app to your command line. The hello-world template uses Devvit.Types.Logger to log information every time a menu app is clicked (See Create a logger to learn more. For now, you'll see the logs as they are produced.

To view logs:

1. Open a command line and navigate to the app directory.
2. Enter devvit logs <subreddit name> to start streaming logs to your console.
3. On a desktop browser, go to your test subreddit.
4. Click on a menu item.
5. You'll see a log appear in your console.

devvit logs r/yourtestsubreddit yourredditname-hello-world

The output should look similar to the following, where the [DEBUG] lines are logs.

============================ streaming logs for a-fancy-hello-to-you on r/testingdevvit456 =============================
[DEBUG] Nov 11 14:10:39 Hello, stranger!
[DEBUG] Nov 11 14:10:43 Post action! Post ID: ysnmsd
[DEBUG] Nov 11 14:10:48 Post action! Post ID: ysnmsd
[DEBUG] Nov 11 14:10:51 Mod action! You clicked on this from the 0 context!
[DEBUG] Nov 11 14:10:55 Subreddit action! Subreddit ID: 7d5f8c

6. To exit the streaming logger, enter CTRL-c.

Update your App

Now that you've got a first version running, let's upload and install an updated version of your app. Here you’ll simply change the title of the first menu item, but you can refer to the tutorials (like Creating a "remind me" app) for how to add more interesting features later.

Change a menu action

Using your favorite editor:

1. Open the main.ts file in your apps directory.
2. Locate the first call to Devvit.addAction.
3. Change the value of name from Custom Post Action to My Fancy Action (this should be on line 8).
4. Save your changes.

When you are done, the first Devvit.addAction should look like this:

Devvit.addAction({
  context: Context.POST,
  name: 'My Fancy Action', // <- Change this line
  description: 'Do something with this post',
  handler: async (event) => {
    const message = `Post action! Post ID: ${event.post?.id}`;
    console.log(message);
    /**
     * We need to return two things from this call:
     *  - success: whether the Action succeeded
     *  - message: A bit of text to show the user as
     *             feedback (confirmation, warning, error, etc.)
     */
    return { success: true, message };
  },
});

Upload a new version

To upload your updated app:

1. Move to the top level of your apps directory.

my-simpler-project     # <- remember, you should be here before uploading
├── devvit.yaml
├── package.json
├── src
│   └── main.ts
├── tsconfig.json
├── yarn.lock

2. Run devvit upload.

Your version number will update automatically.

Update your installation

After you update your app, every subreddit that has installed your app has to manually update to the new version (don’t worry, this won’t last forever). To update your subreddit app installation:

1. Go to Apps I developed.
2. Click on your app's listing. You’ll see a Communities section that shows the subreddits that have installed your app and the version each subreddit is currently using.
3. When a new version of an app is available for a given subreddit, you will see a blue Update button. Click the button and follow the prompts to upgrade each installation.

Next steps

Now you know how to create and deploy apps! Next up, try the following:

1. Create a remind me app.
2. Check out our other app templates.
3. Learn about Reddit API plugins.