Duolingo Stats Card

🦉 A real-time, customizable Duolingo widget that you can embed on your website or markdown files ✨

✨ View Demo · 🐛 Report Bug · 💁🏽 Request Feature

🚀 How to add to your page

Use the demo website to create your customized card! Add the following line to your Github README.md page / website / any markdown file and replace {your-duolingo-username}

<img src="https://duolingo-stats-card.vercel.app/api?username={your-duolingo-username}" alt="Duolingo Stats Card" />

For example, if your Duolingo username is "John_Smith", add the following line (this is in Markdown mode):

![Duolingo Stats Card](https://duolingo-stats-card.vercel.app/api?username=John_Smith)

Want weekly XP, Duolingo scores, hearts, and gems? Deploy your own instance below.

🚀 Deploy using Vercel

To access private Duolingo stats, like your Duolingo proficiency scores, gems, hearts, weekly XP etc, you will need to provide your Duolingo JWT Token. To keep your token secure, you will need to deploy your own Duolingo Stats Card.

Public stats	Public + private stats

1. Click Fork at the top of this repository, then Create fork to make a copy under your GitHub account.

2. Sign in to Vercel with GitHub. Select Add New → Project, find your fork, and click Import. If it isn't listed, allow Vercel to access it through the GitHub permissions prompt.

3. Choose a project name, leave the detected Next.js settings as they are, and click Deploy. Wait for the deployment to finish.

4. Open your new project's Settings → Environment Variables. Add the variables below, selecting Production as the environment for each, and save. Get your token using the steps in the next section.

   Name	Value
   DUOLINGO_JWT	Your Duolingo jwt_token. Treat this like a password.
   DUOLINGO_USERNAME	Your Duolingo username, not your display name. It must belong to the same account as the token.
   DUOLINGO_TIMEZONE	Optional: your time zone, such as America/Los_Angeles. Leave it unset to use UTC.

5. Go to Deployments, open the latest production deployment's ⋯ menu, and select Redeploy so it picks up your saved variables.

6. Once it's ready, open the project's Overview and click its production domain. Your URL will look like https://your-project-name.vercel.app (Vercel may add a suffix if the name is taken). Use this address for your card builder and embeds.

7. In your deployed card builder, enter the username you configured, choose a theme and animation, and tick the fields you want to show. Drag Duo to position it and use its corner handle to resize it. Click Copy Markdown for a GitHub README or Copy HTML for a website, then paste the result into your page.

The copied code already includes your deployment's address and your selected options. To change your card later, reopen the same builder, customize it, and replace the old embed with the newly copied code. The extra stats checkboxes appear only for your configured username when both required variables are set.

🔑 Get your Duolingo JWT

1. Sign in to Duolingo in your browser.
2. Right-click the page and select Inspect to open developer tools.
3. Open Application (Chrome/Edge) or Storage (Firefox), expand Cookies, and select https://www.duolingo.com.
4. Find jwt_token and copy its Value into the DUOLINGO_JWT setting in Vercel. Don't copy the cookie name or share the value.

When the token expires, repeat these steps, update the saved value in Vercel, and redeploy from Deployments → ⋯ → Redeploy.

🎨 Themes

Want to spice up the look and feel of your stats card? You can choose your favorite among 15 different themes!

Simply add the theme parameter to the url like so:

<img src="https://duolingo-stats-card.vercel.app/api?username={your-duolingo-username}&amp;theme={your-theme}" alt="Duolingo Stats Card" />

Note

If you don't specify a theme, it would be rendered like how it's displayed at the top of this doc!

light	dark	github-dark
monokai	tokyonight	nightowl
onedark	shades-of-purple	dracula
cobalt2	sky	beach
purple-gang	mint	leafy

💻 Run locally

Use Node.js 22+ and pnpm 10.30.3. For owner stats, copy .env.example to .env.local and fill in your variables before starting the server. Keep .env.local out of commits.

pnpm install --frozen-lockfile
pnpm dev

Open localhost:3000. Restart the server after changing environment variables.

🙌🏼 Contributing

If you wanna add your custom theme or suggest enhancements, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)