open-saas Documentation

Knows exactly what it is.

Most developers already know the first half of this: the meta tags in your HTML <head>. Those are your <title>, <meta name="description">, and the Open Graph and Twitter card tags that decide how your links look when they're shared. They're worth getting right, and Open SaaS already fills in the important ones for you, so you mostly just swap in your own copy. You can see how they're wired up in the SEO & Performance guide.

Structured data is the half most people skip. It's far less common than meta tags but just as important today, especially now that LLMs lean on it to figure out and recommend what your product actually is.

Schema.org is the vocabulary, and JSON-LD is the format Google (and most LLMs) prefer. You drop a <script type="application/ld+json"> into your HTML, and that's it. There's no rendering impact, no layout shift, nothing to style.

For a SaaS landing page, the types worth including are:

• SoftwareApplication: name, description, URL, category, image, pricing, license. Use the more specific WebApplication subtype if your app runs entirely in the browser.
• WebSite: site-level identity and links to social profiles.
• Organization: who's behind the app.
• FAQPage: turns your FAQ section into rich snippets in Google, and gives LLMs clean Q&A pairs to cite when someone asks about your product.

LLMs love this stuff because it's unambiguous. Instead of inferring what your product is from marketing copy, they can read a structured record that says exactly what it is, what it costs, and who makes it. It's basically a machine-readable elevator pitch.

Here's a complete example you can drop into any React app. It's the trimmed SchemaMarkup component we ship in Open SaaS, but there's nothing framework-specific about it. The same JSON object works as a plain <script> tag in any HTML page:

const schema = {
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "SoftwareApplication",
      "@id": "https://your-saas-app.com/#software",
      name: "Your Open SaaS App",
      description: "Your app's main description and features.",
      url: "https://your-saas-app.com",
      applicationCategory: "BusinessApplication",
      operatingSystem: "Cross-platform",
      image: "https://your-saas-app.com/public-banner.webp",
      offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
    },
    {
      "@type": "WebSite",
      "@id": "https://your-saas-app.com/#website",
      url: "https://your-saas-app.com",
      name: "Your Open SaaS App",
      description: "Your app's main description and features.",
    },
  ],
};

export function SchemaMarkup() {
  return <script type='application/ld+json'>{JSON.stringify(schema)}</script>;
}

You import it once into your landing page and forget about it. Because the landing page is prerendered (see step 1), the script ends up inlined in the static HTML, which is exactly where crawlers and LLMs want to see it.

If your landing page has an FAQ section, add a FAQPage entry too. It's one of the highest-leverage additions for both Google rich snippets and AI answers, because Q&A is already the shape LLMs want to quote.

When you're done, validate with Google's Rich Results Test and the Schema.org validator before deploying.

:::tip[Don't want to wire this up yourself?]
All three of these techniques now ship with the Open SaaS starter, pre-configured and ready to customize. If you're building on it, the prerendered routes, schema markup, and llms.txt are already in place. You can read the rest of this as background and skip to what's new.
:::

3. Publish an llms.txt file Copy Chapter

llms.txt is a fairly new convention. It's a markdown file at the root of your site that gives LLMs a curated index of the pages and resources you actually want them to know about.

It's intentionally not a sitemap. A sitemap is exhaustive and aimed at crawlers. llms.txt is short, hand-picked, and aimed at language models trying to answer questions about you. Think of it as a README for your site, written for an AI.

The minimum useful version is:

# Your SaaS App

> One-line description of what your SaaS does and who it's for.

A longer paragraph giving context: the problem your app solves, the kind of
user it serves, and the key value it delivers.

## Core pages
- [Home](https://your-saas-app.com): Landing page with features, pricing, and FAQ
- [Pricing](https://your-saas-app.com/pricing): Subscription plans and pricing

## Documentation

- [Docs](https://docs.your-saas-app.com): Product documentation and guides

## Resources

- [Blog](https://your-saas-app.com/blog): Updates, tutorials, and announcements
- [GitHub](https://github.com/your-org/your-repo): Open source code

Drop it at public/llms.txt and it's served at https://your-saas-app.com/llms.txt.

If you've got a docs site or a blog, it's worth generating the file at build time so it stays current. We do that for opensaas.sh with a small Node script at scripts/generate-llms-txt.mjs. It reads the blog frontmatter and writes out an updated llms.txt before each deploy. About 90 lines, no dependencies, easy to lift into any project. There are also some plugins and npm packages that do this automatically, but I find that having custom control over what goes in the file is better.

Keep the file short and intentional. Think of it more like an index or a map so LLMs and agents know where to go to find the most relevant content. You can check out the Open SaaS llms.txt for a proper example in production.

How the three fit together Copy Chapter

Here's a quick recap on why these three tips fit together:

• Prerendering makes your content broadly visible to all crawlers and AI bots and improves site performance (e.g. load speed).
• JSON-LD makes that content understandable to search engines and AI.
• llms.txt makes your site easy for AI tools to navigate.

It's important to note that without prerendering, your structured data will just sit in a JS bundle that classic and AI crawlers might never execute. So my advice would be to get prerendering for your landing page in place first, then layer the other two on top.

What's new in Open SaaS Copy Chapter

We just shipped all three of these building blocks in the Open SaaS template, so if you're using it you don't have to wire any of this up from scratch:

• prerender: true is on by default for the landing page and pricing page.
• A JSON-LD SchemaMarkup component lives at src/landing-page/components/SchemaMarkup.tsx and is already rendered on the landing page.
• A placeholder llms.txt ships at template/app/public/llms.txt.
• Docs, like the SEO & Performance, the guided tour, plus deploying guides all walk you through customizing all of it before you ship:
  • The head meta tags in the main config file (title, description, OG tags).
  • The schema object in SchemaMarkup.tsx (name, URL, description, FAQ entries).
  • The public/llms.txt file (replace placeholder URLs and copy).

It's about 15 minutes of work and your landing page is in good shape for both search engines and the AI side of search.

Wrapping up Copy Chapter

If you only do one of these, do prerendering. It fixes the foundational problem (content not in HTML) that everything else depends on. Once that's in, JSON-LD and llms.txt are both small, isolated additions with outsized payoff.

If you want a working reference for all of it, Open SaaS is free and open-source, and the GitHub repo has the actual code for the schema component, the llms.txt generator, and the prerendered routes. If you build something cool with it, drop in our Discord and let us know.

And if you found this useful, a star on GitHub helps more devs find the project. Thanks for reading.

Opensaas Sh Blog Src Content Docs General Admin Dashboard (`opensaas-sh/blog/src/content/docs/general/admin-dashboard.mdx`) Copy Section

title: Admin Dashboard
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

import adminDashboard from '@assets/admin/admin-dashboard.png';
import dbStudio from '@assets/stripe/db-studio.png';
import { Image } from 'astro:assets';

This is a reference on how the Admin dashboard, available at /admin, is set up.

Permissions Copy Chapter

The Admin dashboard is only accessible to users with the isAdmin field set to true.

model User {
  id                        String          @id @default(uuid())
  createdAt                 DateTime        @default(now())

  email                     String?         @unique
  username                  String?         @unique
  isAdmin                   Boolean         @default(false)
  //...

To give yourself administrator priveledges, make sure you add your email addresses to the ADMIN_EMAILS environment variable in .env.server file before registering/logging in with that email address:

[email protected]

// or add many admins with a comma-separated list

[email protected],[email protected],[email protected]

Or if you've already logged in with an email address that you want to give admin priveledges to, you can run the following command in a separate terminal window to update the user's isAdmin field manually:

wasp db studio

:::tip[Star our Repo on GitHub! 🌟]
We've packed in a ton of features and love into this SaaS starter, and offer it all to you for free!

If you're finding this template and its guides useful, consider giving us a star on GitHub
:::

Admin Dashboard Pages Copy Chapter

Analytics Dashboard Copy Section

The Admin analytics dashboard is a single place for you to view your most important metrics and perform some admin tasks. At the moment, it pulls data from:

• Payment Processor:
  • Total revenue.
  • Revenue for each day of the past week.
• Google or Plausible:
  • Total number of page views (non-unique).
  • Percentage change in page views from the previous day.
  • Top sources/referrers with unique visitor count (i.e. how many people came from that source to your app).
• Database:
  • Total number of registered users.
  • Daily change in number of registered users .
  • Total number of paying users.
  • Daily change in number of paying users.

These metrics are aggregated within the background job calculateDailyStatsJob, which by default is run every hour. You can change the frequency of this job by modifying its cron field:

import { job, type Spec } from "@wasp.sh/spec";
import { calculateDailyStatsJob } from "./stats" with { type: "ref" };

export const analyticsSpec: Spec = [
  job(calculateDailyStatsJob, {
    executor: "PgBoss",
    schedule: {
      cron: "0 * * * *", // Every hour. useful in production.
      // cron: "* * * * *" // Every minute. useful for debugging.
    },
    entities: ["User", "DailyStats", "Logs", "PageViewSource"],
  }),
];

For more info on Wasp's recurring background jobs, check out the Wasp Jobs docs.

For a guide on how to integrate these services so that you can view your analytics via the dashboard, check out the Payment Integrations and Analytics guide of the docs.

:::note[Help us improve]
We're always looking to improve the Admin dashboard. If you feel something is missing or could be improved, consider opening an issue or submitting a pull request
:::

Users Copy Section

The Users page is where you can view all your users and their most important details. You can also search and filter users by:

• Email address.
• Subscription/payment status.
• Admin status.

Opensaas Sh Blog Src Content Docs General Privacy Policy (`opensaas-sh/blog/src/content/docs/general/privacy-policy.mdx`) Copy Section

title: Privacy Policy sidebar: hidden: true Copy Chapter

OpenSaaS.sh

Last updated: 2026-01-13

OpenSaaS.sh ("we", "our", or "us") is committed to protecting your privacy. This Privacy Policy explains how we collect, use, disclose, and safeguard your information when you visit our website (https://opensaas.sh).

Please read this privacy policy carefully. If you do not agree with the terms of this privacy policy, please do not access the site.

What Data Do We Collect? Copy Chapter

OpenSaaS.sh collects the following types of personal data:

• IP address
• browser type
• pages visited
• time spent on pages

How Do We Collect Your Data? Copy Chapter

You directly provide OpenSaaS.sh with most of the data we collect. We collect data and process data when you:

• Use or view our website via your browser's cookies.

How Will We Use Your Data? Copy Chapter

OpenSaaS.sh collects your data so that we can:

• Analyze website traffic
• Improve our website
• Understand how visitors use our site

Third-Party Services Copy Chapter

We use third-party services to help us operate our website, conduct our business, and provide services to you. These services may collect information about your visit to our website.

We use the following third-party services:

• Google Analytics
• REO.dev

These third-party service providers have their own privacy policies addressing how they use your information. We encourage you to review their privacy policies.

We only share information with these parties as necessary to provide our services to you, and they are obligated to keep your information confidential and secure.

How Do We Store Your Data? Copy Chapter

OpenSaaS.sh securely stores your data using industry-standard security measures.

Security Measures Copy Section

We implement the following security measures to protect your data:

• SSL/TLS encryption
• Secure cloud infrastructure

Data Retention Copy Section

OpenSaaS.sh will keep your personal data for as long as necessary to fulfill the purposes outlined in this privacy policy. Once this period has expired, we will delete your data securely.

Marketing Copy Chapter

OpenSaaS.sh would like to send you information about products and services of ours that we think you might like.

If you have agreed to receive marketing, you may always opt out at a later date. You have the right at any time to stop OpenSaaS.sh from contacting you for marketing purposes.

If you no longer wish to be contacted for marketing purposes, please contact us at [email protected].

Your Data Protection Rights Copy Chapter

OpenSaaS.sh would like to make sure you are fully aware of all of your data protection rights. Every user is entitled to the following:

The right to access – You have the right to request copies of your personal data. We may charge you a small fee for this service.

The right to rectification – You have the right to request that we correct any information you believe is inaccurate. You also have the right to request that we complete information you believe is incomplete.

The right to erasure – You have the right to request that we erase your personal data, under certain conditions.

The right to restrict processing – You have the right to request that we restrict the processing of your personal data, under certain conditions.

The right to object to processing – You have the right to object to our processing of your personal data, under certain conditions.

The right to data portability – You have the right to request that we transfer the data that we have collected to another organization, or directly to you, under certain conditions.

If you make a request, we have one month to respond to you. If you would like to exercise any of these rights, please contact us at:

• Email: [email protected]

Cookies Copy Chapter

Cookies are text files placed on your computer to collect standard Internet log information and visitor behavior information. When you visit our website, we may collect information from you automatically through cookies or similar technology.

For further information, visit allaboutcookies.org.

How Do We Use Cookies? Copy Section

OpenSaaS.sh uses cookies in a range of ways to improve your experience on our website, including:

• Functional cookies: Keeping you signed in and remembering your preferences
• Analytics cookies: Understanding how you use our website to improve our services

Managing Cookies Copy Section

You can set your browser not to accept cookies, and the website allaboutcookies.org tells you how to remove cookies from your browser. However, in a few cases, some of our website features may not function as a result.

Privacy Policies of Other Websites Copy Chapter

Our website may contain links to other websites. Our privacy policy applies only to our website, so if you click on a link to another website, you should read their privacy policy.

Changes to Our Privacy Policy Copy Chapter

OpenSaaS.sh keeps its privacy policy under regular review and places any updates on this web page. This privacy policy was last updated on 2026-01-13.

How to Contact Us Copy Chapter

If you have any questions about OpenSaaS.sh's privacy policy, the data we hold on you, or you would like to exercise one of your data protection rights, please do not hesitate to contact us at:

• Email: [email protected]

How to Contact the Appropriate Authority Copy Chapter

Should you wish to report a complaint or if you feel that OpenSaaS.sh has not addressed your concern in a satisfactory manner, you may contact your local data protection supervisory authority.

This privacy policy is based on the GDPR privacy policy template from GDPR.eu.

Opensaas Sh Blog Src Content Docs Guides Analytics (`opensaas-sh/blog/src/content/docs/guides/analytics.md`) Copy Section

title: Analytics
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

This guide will show you how to integrate analytics for your app. You can choose between Google Analytics and Plausible.

Google Analytics is free, but uses cookies, so you'll probably want/need to implement the Cookie Consent Modal when using it.

Plausible is an open-source, privacy-friendly alternative to Google Analytics. You DO NOT have to use the cookie consent modal with Plausible, as it does not use cookies. It's also easier to use than Google if you use their hosted service, but be aware it is a paid feature. It is completely free if you want to self-host it, although this comes with some additional setup steps.

If you're looking to add analytics to your blog, you can follow the Adding Analytics to your Blog section at the end of this guide.

Plausible Copy Chapter

Hosted Plausible Copy Section

Sign up for a hosted Plausible account here.

Once you've signed up, you'll be taken to your dashboard. Create your site by adding your domain. Your domain is also your PLAUSIBLE_SITE_ID in your .env.server file. Make sure to add it.

PLAUSIBLE_SITE_ID=<your domain without www>

After adding your domain, you'll be taken to a page with your Plausible script tag. Copy and paste this script tag into the app's head config, defined in the src/client/head.wasp.ts file.

import { type App } from "@wasp.sh/spec";

export const head: App["head"] = [
  // ...
  "<your plausible script tag here>",
];

Go back to your Plausible dashboard, click on your username in the top right, and click on the Settings tab. Scroll down, find your API key and paste it into your .env.server file under the PLAUSIBLE_API_KEY variable.

:::note[No Cookies]
Plausible does not use cookies, so you don't need to add it to your Cookie Consent Modal, hence the script can be added directly to the app's head config in the src/client/head.wasp.ts file.
:::

Self-hosted Plausible Copy Section

Plausible, being an open-source project, allows you to self-host your analytics. This is a great option if you want to keep your data private and not pay for the hosted service.

coming soon...

...until then, check out the official documentation.

:::tip[Contribute!]
If you'd like to help us write this guide, click the "Edit page" button at the bottom of this page

As a completely free, open-source project, we appreciate any help 🙏
:::

Google Analytics Copy Chapter

First off, head over to src/analytics/stats.ts and switch out the Plausible Provider for Google Analytics so that your background (cron) job fetches the data from Google Analytics for your Admin Dashboard:

//...
import { getDailyPageViews, getSources } from './providers/plausibleAnalyticsUtils';
import { getDailyPageViews, getSources } from './providers/googleAnalyticsUtils';

export const calculateDailyStats: DailyStatsJob<never, void> = async (_args, context) => { 
  //...
}

Next, make sure you sign up for Google analytics, then go to your Admin panel in the bottom of the left sidebar and then create a "Property" for your app.

Once you've created a new Property, some Installation Instructions will pop up. Select install manually where you should see a string that looks like this:

"">https://www.googletagmanager.com/gtag/js?id=<your-google-analytics-id>

and copy and paste the Google Analytics ID into your .env.client file to get it working with the Cookie Consent Modal provided with this template:

REACT_APP_GOOGLE_ANALYTICS_ID=<your-google-analytics-id> # e.g. G-1234567890

:::tip[noscript]
In the Installation Instructions, Google Tag Manager might also instruct you to paste the noscript code snippet immediately after the opening `` tag.
You should skip this step because this snippet is activated only if users try to browse your app without JavaScript enabled, which is very rare and React needs JS anyway.
:::

Then, set up the Google Analytics API access by following these steps:

1. Set up a Google Cloud project: If you haven't already, start by setting up a project in the Google Cloud Console.

2. Enable the Google Analytics API for your project: Navigate to the "Library" in the Google Cloud Console and search for the "Google Analytics Data API" (for Google Analytics 4 properties) and enable it.

3. Create credentials: Now go to the "Credentials" tab within your Google Cloud project, click on + credentials, and create a new service account key. First, give it a name. Then, under "Grant this service account access to project", choose viewer.

4. Create Credentials: When you go back to Credentials page, you should see a new service account listed under "Service Accounts". It will be a long email address to ends with @your-project-id.iam.gserviceaccount.com. Click on the service account name to go to the service account details page.

   • Under "Keys" in the service account details page, click "Add Key" and choose Create new key.

   • Select "JSON", then click "Create" to download your new service account's JSON key file. Keep this file secure and don't add it to your git repo as it grants access to your Google Analytics data.

5. Update your Google Anayltics Settings: Go back to your Google Analytics dashboard, and click on the Admin section in the left sidebar. Under Property Settings > Property > Property Access Management Add the service account email address (the one that ends with @your-project-id.iam.gserviceaccount.com) and give it Viewer permissions.

6. Encode and add the Credentials: Add the client_email and the private_key from your JSON Key file into your .env.server file. But be careful! Because Google uses a special PEM private key, you need to first convert the key to base64, otherwise you will run into errors parsing the key. To do this, in a terminal window, run the command below and paste the output into your .env.server file under the GOOGLE_ANALYTICS_PRIVATE_KEY variable:

   sh Copy

   echo -n "-----BEGIN PRIVATE KEY-----\nMI...A++eK\n-----END PRIVATE KEY-----\n" | base64

7. Add your Google Analytics Property ID: You will find the Property ID in your Google Analytics dashboard in the Admin > Property > Property Settings > Property Details section of your Google Analytics property (not your Google Cloud console). Add this 9-digit number to your .env.server file under the GOOGLE_ANALYTICS_PROPERTY_ID variable.

Adding Analytics to your Blog Copy Chapter

To add your analytics script to your Astro Starlight blog, all you need to do is modify the head property in your blog/astro.config.mjs file.

Below is an example of how to add Google Analytics to your blog:

export default defineConfig({
  site: 'https://opensaas.sh',
  integrations: [
    starlightBlog({ 
      // ...
    }),
    starlight({
      //...
       head: [
        {
          tag: 'script',
          attrs: {
            src: 'https://www.googletagmanager.com/gtag/js?id=<YOUR-GOOGLE-ANALYTICS-ID>',
          },
        },
        {
          tag: 'script',
          content: `
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());
        
          gtag('config', '<YOUR-GOOGLE-ANALYTICS-ID>');
          `,
        },
      ],

Opensaas Sh Blog Src Content Docs Guides Authentication (`opensaas-sh/blog/src/content/docs/guides/authentication.md`) Copy Section

title: Authentication
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

Setting up your app's authentication is easy with Wasp. In fact, it's already set up for you in the src/auth/auth.wasp.ts file:

export const authConfig: Auth = {
  userEntity: "User",
  methods: {
    email: emailAuthMethod,
    google: googleAuthMethod,
    gitHub: gitGubAuthMethod,
    discord: discordAuthMethod,
  },
  onAuthFailedRedirectTo: "/login",
  onAuthSucceededRedirectTo: "/demo-app",
};

The great part is, by defining your auth config in the Wasp Spec, Wasp manages most of the Auth process for you, including the auth-related database entities for user credentials and sessions, as well as auto-generated client components for your app on the fly (aka AuthUI -- you can see them in use in the src/auth folder).

Email Verified Auth Copy Chapter

email method is the default auth method in Open SaaS.

Since it needs to send emails to verify users and reset passwords, it requires an email sender provider: a service it can use to send emails.
A "email sender" provider is configured via the app's emailSender field, defined in the src/server/emailSender.wasp.ts file.

:::caution[Dummy Email Provider]
To make it easy for you to get started, Open SaaS initially comes with the Dummy "email sender" provider, which does not send any emails, but instead logs all email verification links/tokens to the server's console!
You can then follow these links to verify the user and continue with the sign-up process.

import { type EmailSender } from "@wasp.sh/spec";

export const emailSender: EmailSender = {
  provider: "Dummy", // Logs all email verification links/tokens to the server's console.
  defaultFrom: {
    name: "Open SaaS App",
    email: "[email protected]",
  },
};

You can not use the Dummy provider in production and your app will not build until you move to a production-ready provider, such as SendGrid. We outline the process of migrating to SendGrid below.
:::

In order to use the email auth method in production, you'll need to switch from the Dummy "email sender" provider to a production-ready provider like SendGrid:

1. First, set up your app's emailSender in the src/server/emailSender.wasp.ts file by following this guide.
2. Add your SENDGRID_API_KEY to the .env.server file.
3. Make sure the email address you use in the fromField object is the same email address that you configured your SendGrid account to send out emails with. In the end, your config should look something like this:

const emailAuthMethod: EmailAuthConfig = {
  fromField: {
    name: "Open SaaS App",
    // When using SendGrid, you must use the same email address that you configured your account to send out emails with!
    email: "[email protected]",
  },
  // ...
};

export const emailSender: EmailSender = {
  provider: "Dummy",
  provider: "SendGrid",
  defaultFrom: {
    name: "Open SaaS App",
    // When using SendGrid, you must use the same email address that you configured your account to send out emails with!
    email: "[email protected]",
  },
};

And that's it. Wasp will take care of the rest and update your AuthUI components accordingly.

Check out the Wasp Auth docs for more info.

Google, GitHub, & Discord Auth Copy Chapter

We've also customized and pre-built the Google, Discord and GitHub auth flow for you. To start using them, you just need to uncomment out the methods you want in your src/auth/auth.wasp.ts file and obtain the proper API keys to add to your .env.server file.

To create a Google OAuth app and get your Google API keys, follow the instructions in Wasp's Google Auth docs.

To create a GitHub OAuth app and get your GitHub API keys, follow the instructions in Wasp's GitHub Auth docs.

To create a Discord OAuth app and get your Discord API keys, follow the instructions in Wasp's Discord Auth docs

Again, Wasp will take care of the rest and update your AuthUI components accordingly.

Opensaas Sh Blog Src Content Docs Guides Authorization (`opensaas-sh/blog/src/content/docs/guides/authorization.md`) Copy Section

title: Authorization
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

This guide will help you get started with authorization in your SaaS app.

Authorization refers to what users can access in your app. This is useful for differentiating between users who have paid for different subscription tiers (e.g. "hobby" vs "pro"), or between users who have admin privileges and those who do not.

Authorization differs from authentication in that authentication refers to the process of verifying that a user is who they say they are (e.g. logging in with a username and password).

To learn more about the different types of user permissions built into this SaaS template, including Stripe subscription tiers and statuses, check out the User Overview Reference.

Also, check out our blog post to learn more about authorization (access control) in web apps.

Client-side Authorization Copy Section

Open Saas starts with all users having access to the landing page (/), but only authenticated users having access to the rest of the app (e.g. to the /demo-app, or to the /account).

To control which pages require users to be authenticated to access them, you can set the authRequired property of the corresponding page definition in your Wasp Spec:

import { page, route, type Spec } from "@wasp.sh/spec";
import { AccountPage } from "./AccountPage" with { type: "ref" };

export const userSpec: Spec = [
  route("AccountRoute", "/account", page(AccountPage, { authRequired: true })),
];

This will automatically redirect users to the login page if they are not logged in while trying to access that page.

:::caution[Client-side authorization is just for the looks]
Users can manipulate the client code as they wish, meaning that client-side authorization (access control) serves the purpose of ergonomics/user experience, not the purpose of restricting access to sensitive data.

This means that authorization in the client code is a nice-to-have: it is here to make sure users don't get lost in the part of the app they can't work with because data is missing due to them not having access, not to actually restrict them from doing something.

Actually ensuring they don't have access to the data, that is on the server to ensure, via server-side logic that you will implement for authorization.
:::

If you want more fine-grained control over what users can access, there are two Wasp-specific options:

1. When you define the authRequired: true property on the page definition, Wasp automatically passes the User object to the page component. Here you can check for certain user properties before authorizing access:

import { type User } from "wasp/entities";

export function ExamplePage({ user }: { user: User }) {
  if (user.subscriptionStatus === 'past_due') {
    return (<span>Your subscription is past due. Please update your payment information.</span>)
  }
  if (user.subscriptionStatus === 'cancel_at_period_end') {
    return (<span>Your susbscription will end on 01.01.2024</span>)
  }
  if (user.subscriptionStatus === 'active') {
    return (<span>Thanks so much for your support!</span>)
  }
};

2. Or you can take advantage of the useAuth hook and check for certain user properties before authorizing access to certain pages or components:

import { useAuth } from "wasp/client/auth";

export function ExampleComponent() {
  const { data: user } = useAuth();

  return (
    <h1> Hi {user.email || 'there'} 👋 </h1>
  )
}

Server-side Authorization Copy Section

Authorization on the server-side is the core of your access control logic, and determines what users actually can or can't do (unlike client-side authorization logic which is there merely for UX).

You can authorize access to server-side operations by adding a check for a logged-in user on the context.user object which is passed to all operations in Wasp:

export const someServerAction: SomeServerAction<...> = async (args, context) => {
  if (!context.user) {
    throw new HttpError(401); // Throw an error if user is not logged in.
  }

  if (context.user.subscriptionStatus === 'past_due') {
    throw new HttpError(403, 'Your subscription is past due. Please update your payment information.');
  }
  //...
}

Opensaas Sh Blog Src Content Docs Guides Cookie Consent (`opensaas-sh/blog/src/content/docs/guides/cookie-consent.mdx`) Copy Section

title: Cookie Consent Modal
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

import cookieBanner from '@assets/cookie-consent/cookiebanner.png';
import preferences from '@assets/cookie-consent/preferences.png';
import { Image } from 'astro:assets';

Cookie consent banners are annoying, we know. But they are legally required in many countries, so we have to deal with them.

This guide will help you dynamically add or remove cookies from your app via the cookie consent modal that comes with this template.

This is needed for non-essential cookies that are not necessary for the basic functionality of your app, such as analytics cookies or marketing cookies.

The cookie consent modal can be found at app/src/client/components/cookie-consent/ and contains two main files:

1. Banner.tsx - the component that displays the banner at the bottom of the page.
2. Config.ts - the configuration file that contains the cookies/scripts that will be dynamically added.

The Banner.tsx component is imported in app/src/client/App.tsx and is rendered at the bottom of the page, while all the changes to the banner itself are done within the Config.ts file, which we explain below.

Configuration Copy Chapter

We decided to use the vanilla-cookieconsent library to handle the cookie consent. We've set it up to give you some basic functionality, using mostly the default settings. For a full list of options, you can check the official documentation.

Below, we will guide you through the necessary steps to get the cookie consent modal set up for your app.

Google Analytics Copy Section

What's impotant to note for this template is that we are simply using the onAccept callbacks to dynamically add or remove our Google Analytics cookies from the page. In order for it to work correctly with your app, you need to add your Google Analytics ID to your .env.client file.

REACT_APP_GOOGLE_ANALYTICS_ID=G-1234567890

And that's it! The cookie consent modal will now dynamically add or remove the Google Analytics cookies based on the user's choice.

To check if it's working correctly, you can open the browser's developer tools and check the cookies tab. You should see the following cookies being added or removed based on the user's choice:

_ga
_ga... # Google Analytics cookies.
cc_cookie # Cookie Consent cookie. The name of this cookie can be changed in the config file.

Plausible Analytics Copy Section

If you decide to go with Plausible Analytics, you DO NOT need to ask users for their consent to use cookies because Plausible, as a privacy-first analytics provider, does not use cookies. Instead, It collects website usage data anonymously and in aggregate form only, without any personally identifiable information

By avoiding cookies, Plausible Analytics avoids the need for cookie consent banners.

Your Terms / Privacy Policy Copy Section

You should also add a link to your terms and privacy policy within consentModal section of config.language:

language: {
      default: 'en',
      translations: {
        en: {
          consentModal: {
            title: 'We use cookies',
            // ...
            // TODO: Add your own privacy policy and terms and conditions links below.
            footer: `
            <a href="<your-url-here>" target="_blank">Privacy Policy</a>
            <a href="<your-url-here>" target="_blank">Terms and Conditions</a>
                    `,
          },
        },
      },
    }

Allowing Users to Control Certain Cookies (OPTIONAL) Copy Section

If you've added more than just Google Analytics cookies to your app, you can allow users to control which cookies they want to accept or reject. For example, if you've added marketing cookies, you can add a button to the modal that allows users to reject them, while accepting analytics cookies.

To do that, you can change the preferencesModal.sections property in config.language. Any section that you add to preferencesModal.sections must match a linkedCategory in the config.categories property. Make sure you also add a showPreferencesBtn property to consentModal (highlighted below).

Below is an example of what your config might look like if you want to give users the option to control over multiple cookie preferences:

/* Detailed source-code truncated for AI context efficiency. */

For more information on how to do that, check the official documentation.

Opensaas Sh Blog Src Content Docs Guides Deploying (`opensaas-sh/blog/src/content/docs/guides/deploying.mdx`) Copy Section

title: Deploying
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

import stripeListenEvents from '@assets/stripe/listen-to-stripe-events.png';
import npmVersion from '@assets/stripe/npm-version.png';
import stripeSigningSecret from '@assets/stripe/stripe-webhook-signing-secret.png';
import { Image } from 'astro:assets';

Because this SaaS app is a React/NodeJS/Postgres app built on top of Wasp, Open SaaS can take advantage of Wasp's easy, one-command deploy or manual deploy to any provider of your choice.

The simplest and quickest option is to take advantage of Wasp's one-command deploy to Fly.io or Railway.

Or if you prefer to deploy to a different provider, or your frontend and backend separately, you can follow the Deploying Manually section below.

Steps for Deploying Copy Chapter

These are the steps necessary for you to deploy your app. We recommend you follow these steps in order.

• Get your production API keys and environment variables.
• Set your production environment variables on your deployed apps.
• Add the correct redirect URL's to your social auth credentials.
• Set your production settings for your payment provider.
• Customize SEO and discoverability (meta tags, JSON-LD, llms.txt).
• Deploy your App through Wasp Deploy commands or manually to any provider.
• (Optional) Deploy your blog.

Each of these steps is covered in more detail below.

Prerequisites Copy Chapter

AWS S3 CORS configuration Copy Section

If you're storing files in AWS S3, ensure you've listed your production domain
in the bucket's CORS configuration under AllowedOrigins. Check the File
uploading guide for details.

Env Vars Copy Section

Make sure you've got all your API keys and environment variables set up before you deploy.

Payment Processor Vars

In the Payments Processor integration guide, you set up your API keys using test keys and test product ids. You'll need to get the live/production versions of those keys. To get these, repeat the instructions in the Integration Guide without being in test mode. Add the new keys to your deployed environment secrets.

Other Vars

Many of your other environment variables will probably be the same as in development, but you should double-check that they are set correctly for production.

Here are a list of all of them (some of which you may not be using, e.g. Analytics, Social Auth) in case you need to check:

General Vars

• DATABASE_URL
• JWT_SECRET
• PORT (most hosting providers set this for you)
• WASP_WEB_CLIENT_URL
• WASP_SERVER_URL

Open AI API Key

• OPENAI_API_KEY

Sendgrid API Key

• SENDGRID_API_KEY

Social Auth Vars

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET

Analytics Vars

• REACT_APP_PLAUSIBLE_ANALYTICS_ID (for client-side)
• PLAUSIBLE_API_KEY
• PLAUSIBLE_SITE_ID
• PLAUSIBLE_BASE_URL
• REACT_APP_GOOGLE_ANALYTICS_ID (for client-side)
• GOOGLE_ANALYTICS_CLIENT_EMAIL
• GOOGLE_ANALYTICS_PROPERTY_ID
• GOOGLE_ANALYTICS_PRIVATE_KEY
  (Make sure you convert the private key within the JSON file to base64 first with echo -n "PRIVATE_KEY" | base64. See the Analytics docs for more info)

AWS S3 Vars

• AWS_S3_IAM_ACCESS_KEY
• AWS_S3_IAM_SECRET_KEY
• AWS_S3_FILES_BUCKET
• AWS_S3_REGION

:::tip[Deployed? Get some swag! 👕]

Do you have an Open SaaS app running in production? If yes, we'd love to send some swag your way! All you need to do is fill out this form and we'll make it happen.

:::

Adding Server Redirect URL's to Social Auth Copy Chapter

After deploying your server, you need to add the correct redirect URIs to the credential settings. For this, refer to the guides from the Wasp Docs.

Payment Providers Production Settings Copy Chapter

Stripe Copy Section

Now you need to set up your stripe webhook for production use. Below are some important steps and considerations you should take as you prepare to deploy your app to production.

Stripe API Versions

When you create your Stripe account, Stripe will automatically assign you to their latest API version at that time. This API version is important because it determines the structure of the responses Stripe sends to your webhook, as well as the structure it expects of the requests you make toward the Stripe API.

Because this template was built with a specific version of the Stripe API in mind, it could be that your Stripe account is set to a different API version.

:::note

const STRIPE_API_VERSION = "2025-04-30.basil"; // or e.g. 2023-08-16 if using older format

export const stripeApi = new Stripe(env.STRIPE_API_KEY, {
  apiVersion: STRIPE_API_VERSION,
});

When you specify a specific API version in stripeApi, the requests you send to Stripe from your server, along with their responses, will match that API version. On the other hand, Stripe will send all other events to your webhook that didn't originate as a request sent from your server, like those made after a user completes a payment on checkout, using the default API version of the API.

This is why it's important to make sure the API version in stripeApi also matches the API version in your Stripe account, and to thoroughly test any changes you make to stripeApi before deploying to production.
:::

To make sure your app is consistent with your Stripe account, here are some steps you can follow:

1. You can find your default API version in the Stripe dashboard under the Developers section.
2. Check that the API version in your /src/payment/stripe/stripeApi.ts file matches the default API version in your dashboard:
   ts title="stripeapi.ts" {1} Copy

   const STRIPE_API_VERSION = "2025-04-30.basil"; // or e.g. 2023-08-16 if using older format
   
   export const stripeApi = new Stripe(env.STRIPE_API_KEY, {
     apiVersion: STRIPE_API_VERSION,
   });

3. If they don't match, you can upgrade/downgrade your Stripe NPM package in package.json to match the API version in your dashboard:

• If your default version on the Stripe dashboard is also the latest version of the API, you can simply upgrade your Stripe NPM package to the latest version.
• If your default version on the Stripe dashboard is not the latest version, and you don't want to upgrade to the latest version, because e.g. you have other projects that depend on the current version, you can find and install the Stripe NPM package version that matches your default API version by following these steps:

  • Find and note the date of your default API version in the developer dashboard.

  • Go to the Stripe NPM package page and hover over Published date column until you find the package release that matches your version. For example, here we find the NPM version 13.x.x matches the API version of 2023-08-16.

  • Install the correct version of the Stripe NPM package by running:

    sh Copy

    npm install [email protected] # e.g. npm install [email protected]

4. Test your app thoroughly to make sure that the changes you made to stripeApi are working as expected before deploying to production.

Creating Your Production Webhook

1. Go to https://dashboard.stripe.com/webhooks

2. Click on + add endpoint

3. Enter your endpoint url, which will be the url of your deployed server + /payments-webhook, e.g. https://open-saas-wasp-sh-server.fly.dev/payments-webhook

4. Select the events you want to listen to. These should be the same events you're consuming in your webhook which are handled in src/payment/stripe/webhook.ts:

5. After that, go to the webhook you just created and reveal the new signing secret.

6. Add this secret to your deployed server's STRIPE_WEBHOOK_SECRET environment variable. If you've deployed to Fly.io, you can do that easily with the following command:

   sh Copy

   wasp deploy fly cmd --context server secrets set STRIPE_WEBHOOK_SECRET=whsec_...

Lemon Squeezy Copy Section

Creating Your Production Webhook

To set up your Lemon Squeezy webhook, you'll need the URL of you newly deployed server + /payments-webhook, e.g. https://open-saas-wasp-sh-server.fly.dev/payments-webhook.

With the webhook url ready, go to your Lemon Squeezy Webhooks Dashboard:

1. Click the + button.
2. Add the webhook forwarding url to the Callback URL section.
3. Give your webhook a signing secret (a long, random string).
4. Add this signing secret to your server's production environment variables under LEMONSQUEEZY_WEBHOOK_SECRET.
5. Make sure to select at least the following updates to be sent:
   • order_created
   • subscription_created
   • subscription_updated
   • subscription_cancelled
6. Click save.

Polar Copy Section

Turning off the Sandbox mode

Make sure to turn off the sandbox mode in your server's production environemnt:

POLAR_SANDBOX_MODE=false

Creating Your Production Webhook

To set up your Polar webhook, you'll need the URL of your newly deployed server + /payments-webhook, e.g. https://open-saas-wasp-sh-server.fly.dev/payments-webhook.

With the webhook URL ready, in your Polar Dashboard:

1. Navigate to Settings > Webhooks.
2. Click the Add Endpoint button.
3. In the URL field, paste your production forwarding address.
4. Set the Format to "Raw".
5. Select the following events to listen for:
   • order.paid
   • subscription.updated
6. Click Save.
7. Copy the generated webhook secret and set it as the POLAR_WEBHOOK_SECRET environment variable in production.

Paddle Copy Section

Turning off the Sandbox mode

Make sure to turn off the sandbox mode in your production environment, for both the server and the client:

PADDLE_SANDBOX_MODE=false

REACT_APP_PADDLE_SANDBOX_MODE=false

Setting the Default Payment Link

In production, Paddle requires a default payment link before it can open a checkout. It must be an https URL on a domain you've had approved by Paddle.

In your Paddle Dashboard:

1. Navigate to Checkout > Checkout configuration.
2. Set the Default payment link to your deployed app's URL, e.g. https://opensaas.sh.
3. Click Save.

Creating Your Production Webhook

To set up your Paddle webhook, you'll need the URL of your newly deployed server + /payments-webhook, e.g. https://open-saas-wasp-sh-server.fly.dev/payments-webhook.

With the webhook URL ready, in your Paddle Dashboard:

1. Navigate to Events > Notifications.
2. Click the + New destination button.
3. Fill in the Description (e.g. "Open SaaS Production").
4. Set the Notification Type to Webhook.
5. In the URL field, paste your production webhook URL.
6. Set the Usage type to Both.
7. Select the following events to listen for:
   • transaction.completed
   • subscription.updated
   • subscription.canceled
8. Click Save.
9. Click on your newly created destination in the Events > Notifications list to open it.
10. Click copy on the Secret key and set it as the PADDLE_WEBHOOK_SECRET environment variable in production.

Customizing SEO and Discoverability Copy Chapter

Before deploying, make sure your app's meta tags, JSON-LD schema, and llms.txt reflect your production URL and content so search engines and AI/LLM tools can index and recommend your app correctly. See the SEO guide for details.

Deploying your App Copy Chapter

Deploying to Fly.io Copy Section

Fly.io is a platform for running your apps globally. It's a great choice for deploying your SaaS app because it's free to get started, can host your entire full-stack app in one place, scales well, and has one-command deploy integration with Wasp.

Wasp provides the handy wasp deploy command to deploy your entire full-stack app (DB, server, and client) in one command.

To learn how, please follow the detailed guide for deploying to Fly via the Wasp CLI from the Wasp documentation. We suggest you follow this guide carefully to get your app deployed.

:::caution[Setting Environment Variables]
Remember, because we've set certain client-side env variables, make sure to pass them to the wasp deploy commands so that they can be included in the build:

REACT_APP_CLIENT_ENV_VAR_1=<...> REACT_APP_CLIENT_ENV_VAR_2=<...> wasp deploy

The wasp deploy command will also take care of setting the following server-side environment variables for you so you don't have to:

• DATABASE_URL
• PORT
• JWT_SECRET
• WASP_WEB_CLIENT_URL
• WASP_SERVER_URL

For setting the remaining server-side environment variables, please refer to the Deploying with the Wasp CLI Guide.
:::

Deploying Manually Copy Section

If you prefer to deploy manually, your frontend and backend separately, or just prefer using your favorite provider you can follow Wasp's Manual Deployment Guide.

:::caution[Client-side Environment Variables]
Remember to always set additional client-side environment variables, such as REACT_APP_STRIPE_CUSTOMER_PORTAL by appending them to the build command, e.g.

REACT_APP_CLIENT_ENV_VAR_1=<...> npm run build

:::

:::note[Server Health Checks]
If your provider runs health checks against your server, point them at the /up endpoint (e.g. https://your-server-url.com/up). Wasp doesn't serve anything at / in production.
:::

Deploying your Blog Copy Chapter

Deploying your Astro Starlight blog is a bit different than deploying your SaaS app. As an example, we will show you how to deploy your blog for free to Netlify. You will need a Netlify account and Netlify CLI installed to follow these instructions.

Make sure you are logged in with Netlify CLI:

• You can check if you are logged in with netlify status.
• You can log in with netlify login.

Position yourself in the blog directory and run the following command:

npm run build

This will build your blog into the blog/dist directory. Now you can deploy your blog to Netlify with the following command:

netlify deploy

Select the dist directory as the deploy path.

Finally, if the deployment looks good, you can deploy your blog to production with the following command:

netlify deploy --prod

Opensaas Sh Blog Src Content Docs Guides Email Sending (`opensaas-sh/blog/src/content/docs/guides/email-sending.mdx`) Copy Section

title: Email Sending
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

import { TabItem, Tabs } from '@astrojs/starlight/components';

This guide explains how to use the integrated email sender and how you can integrate your own account in this template.

Sending Emails Copy Chapter

The `Dummy` Email Provider (for Local Dev Only) Copy Section

By default we've set up the email sender to use the Dummy provider. This is for local development only and no emails will actually be sent out!
To obtain an email verification token/link, you must check the server logs on initial sign up. You can click this link to verify your email and continue with the sign up process.

import { type EmailSender } from "@wasp.sh/spec";

export const emailSender: EmailSender = {
  provider: "Dummy",
  defaultFrom: {
    name: "Open SaaS App",
    email: "[email protected]",
  },
};

Note that your app will not build if using the Dummy provider and you must switch to a production-ready provider in order to do so.

Using a Production-Ready Email Provider (e.g. SendGrid) Copy Section

To change your email provider to a production-ready one, such as SendGrid, you'll want to configure your emailSender like so:

import { type EmailSender } from "@wasp.sh/spec";

export const emailSender: EmailSender = {
  provider: "SendGrid",
  defaultFrom: {
    name: "Open SaaS App",
    // When using SendGrid, you must use the same email address that you configured your account to send out emails with!
    email: "[email protected]",
  },
};

This means that you can send emails from your app using the send function from the email modul provided by Wasp:

import { emailSender } from "wasp/server/email";

//...

  if (subscription.cancel_at_period_end) {
    await emailSender.send({
      to: customer.email,
      subject: 'We hate to see you go :(',
      text: 'We hate to see you go. Here is a sweet offer...',
      html: 'We hate to see you go. Here is a sweet offer...',
    });
  }

In the example above, you can see that we're sending an email to the customer when we receive a cancel subscription event within the Stripe webhook.

This is a powerful feature and super simple to use.

Integrate your email sender Copy Chapter

To set up your email sender, you first need an account with one of the supported email providers.

Make sure to change the `defaultFrom` email address in the `src/server/emailSender.wasp.ts` file to use the same email address that you configured your account to send out emails with!

```ts title="src/server/emailSender.wasp.ts" {5}
export const emailSender: EmailSender = {
  provider: "SendGrid",
  defaultFrom: {
    name: "Open SaaS App",
    email: "[email protected]", // Same email address you configured your SendGrid account to send emails with!
  },
};
```

Make sure to change the `defaultFrom` email address in the `src/server/emailSender.wasp.ts` file to use the same email address that you configured your account to send out emails with!

```ts title="src/server/emailSender.wasp.ts" {5}
export const emailSender: EmailSender = {
  provider: "Mailgun",
  defaultFrom: {
    name: "Open SaaS App",
    email: "[email protected]", // Same email address you configured your Mailgun account to send emails with!
  },
};
```

If you want more detailed info, or would like to use SMTP, check out the Wasp docs.

Opensaas Sh Blog Src Content Docs Guides File Uploading (`opensaas-sh/blog/src/content/docs/guides/file-uploading.mdx`) Copy Section

title: File Uploading
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

import cors from '@assets/file-uploads/cors.png';
import createBucket from '@assets/file-uploads/create-bucket.png';
import defaultSettings from '@assets/file-uploads/default-settings.png';
import findS3 from '@assets/file-uploads/find-s3.png';
import keys from '@assets/file-uploads/keys.png';
import newBucket from '@assets/file-uploads/new-bucket.png';
import permissions from '@assets/file-uploads/permissions.png';
import username from '@assets/file-uploads/username.png';
import { Image } from 'astro:assets';

This guide will show you how to set up file uploading in your SaaS app.

There are two options we recommend:

1. Using AWS S3 with presigned URLS for secure file storage.
2. Using Multer middleware to upload files to your own server.

We recommend using AWS S3 as it's a scalable, secure option, that can handle a large amount of storage.

If you're just looking to upload small files and don't expect your app to grow to a large scale, you can use Multer to upload files to your app's server.

:::tip[Star our Repo on GitHub! 🌟]
We've packed in a ton of features and love into this SaaS starter, and offer it all to you for free!

If you're finding this template and its guides useful, consider giving us a star on GitHub
:::

Using AWS S3 Copy Chapter

How presigned URLs work Copy Section

Presigned URLs are URLs that have been signed with your AWS credentials and can be used to upload files to your S3 bucket. They are time-limited and can be generated on the server and sent to the client to upload files directly to S3.

The process of generating a presigned URL is as follows:

1. The client sends a request to the server to upload a file.
2. The server generates a presigned URL using its AWS credentials.
3. The server sends the presigned URL to the client.
4. The client uses the presigned URL to upload the file directly to S3 before the URL expires.

We use this method to upload files to S3 because it is more secure than uploading files directly from the client to S3. It also allows us to keep our AWS credentials private and not expose them to the client.

To use presigned URLs, we'll need to set up an S3 bucket and get our AWS credentials.

Create an AWS Account Copy Section

Before you begin, you'll need to create an AWS account. AWS accounts are free to create and are split up into:

1. Root account.
2. IAM users.

You'll need to first create a root account, and then an IAM user for your SaaS app before you can start uploading files to S3.

To do so, follow the steps in this external guide: Creating IAM users and S3 buckets in AWS.

Create an AWS S3 Bucket Copy Section

Once you are logged in with your IAM user, you'll need to create an S3 bucket to store your files:

1. Navigate to the S3 service in the AWS console.

2. Click on the Create bucket button.

3. Fill in the bucket name and region.

4. Leave all the settings as default and click Create bucket.

Change the CORS settings Copy Section

Now we need to change some permissions on the bucket to allow for file uploads from your app:

1. Click on the bucket you just created.

2. Click on the Permissions tab.

3. Scroll down to the Cross-origin resource sharing (CORS) section and click Edit.

4. Insert the correct CORS configuration and click Save changes. You can
   copy-paste most of the config below, but you must edit the
   AllowedOrigins field to fit your app. Include http://localhost:3000 for
   local development, and https://<your domain> for production.

   If you don't yet have a domain name, just list http://localhost:3000 for
   now. We'll remind you to add your domain before deploying to production in
   the Deployment docs.

   json {11,12} Copy

   [
       {
           "AllowedHeaders": [
               "*"
           ],
           "AllowedMethods": [
               "POST",
               "GET"
           ],
           "AllowedOrigins": [
               "http://localhost:3000",
               "https://<your-domain>"
           ],
           "ExposeHeaders": []
       }
   ]

Get your AWS S3 credentials Copy Section

Now that you have your S3 bucket set up, you'll need to get your S3 credentials to use in your app:

1. Click on your username in the top right corner of the AWS console and select Security Credentials.

2. Scroll down to the Access keys section.

3. Click on Create Access Key.

4. Select the Application running on an AWS service option and create the access key.

5. Copy the Access key ID and Secret access key and paste them in your src/app/.env.server file:

   sh Copy

   AWS_S3_IAM_ACCESS_KEY=ACK...
     AWS_S3_IAM_SECRET_KEY=t+33a...
     AWS_S3_FILES_BUCKET=your-bucket-name
     AWS_S3_REGION=your-region // (e.g. us-west-2)

:::tip[Star our Repo on GitHub! 🌟]
We've packed in a ton of features and love into this SaaS starter, and offer it all to you for free!

If you're finding this template and its guides useful, consider giving us a star on GitHub
:::

Using and Customizing File Uploads with S3 in your App Copy Section

With your S3 bucket set up and your AWS credentials in place, you can now start uploading files in your app using presigned URLs by navigating to localhost:3000/file-upload and uploading a file.

To begin customizing file uploads, is important to know where everything lives in your app. Here's a quick overview:

• schema.prisma:
  • The File model can be found here. Here you can modify the fields to suit your needs.
• src/file-upload/file-upload.wasp.ts:
  • The file upload routes, queries, and actions are declared here in the Wasp Spec.
• src/file-upload/FileUploadPage.tsx:
  • The FileUploadPage component is where the file upload form lives. It also allows you to download the file from S3 by calling the getDownloadFileSignedURL based on that files key in the app DB.
• src/file-upload/operations.ts:
  • The createFileUploadUrl action lives here and calls the getUploadFileSignedURLFromS3 within it using your AWS credentials before passing it to the client. This function stores the files in the S3 bucket within folders named after the user's ID, so that each user's files are stored separately.
  • The getAllFilesByUser fetches all File information uploaded by the user. Note that the files do not exist in the app database, but rather the file data, its name and its key, which is used to fetch the file from S3.
  • The getDownloadFileSignedURL query fetches the presigned URL for a file to be downloaded from S3 using the file's key stored in the app's database.

Cleaning up "orphaned" files in S3 Copy Section

In the current logic, files are first deleted from the app's database before attempting to delete them from S3. If, for some reason, the S3 deletion were to fail, the file would remain in S3 and not in the app's database and be orphaned:

export const deleteFile: DeleteFile<DeleteFileInput, File> = async (
  rawArgs,
  context,
) => {
  // ...
  const deletedFile = await context.entities.File.delete({
    where: {
      id: args.id,
      user: {
        id: context.user.id,
      },
    },
  });

  try {
    await deleteFileFromS3({ s3Key: deletedFile.s3Key });
  } catch (error) {
    console.error(
      `S3 deletion failed. Orphaned file s3Key: ${deletedFile.s3Key}`,
      error,
    );
  }
};

To clean up these orphaned files, you can add a cleanup job (that runs at an interval of your choosing) to:

1. Fetch all file keys from S3.
2. Fetch all file keys from the app's database.
3. Compare the two lists and delete any files from S3 that are not in the database.

Here's an example of how you could implement this:

import { job, type Spec } from "@wasp.sh/spec";
import { cleanUpOrphanedFilesS3Job } from "./workers" with { type: "ref" };

export const fileUploadSpec: Spec = [
  // ...
  job(cleanUpOrphanedFilesS3Job, {
    executor: "PgBoss",
    schedule: {
      cron: "0 5 * * 0", // Every week on Sunday at 5am.
    },
    entities: ["File"],
  }),
];

/* Detailed source-code truncated for AI context efficiency. */

Using Multer to upload files to your server Copy Chapter

If you're looking to upload files to the app server, you can use the Multer middleware to handle file uploads. This will allow you to store files on your server and is a good option if you need a quick and dirty, free solution for simple file uploads.

To set up file uploads using Multer, follow the Wasp integration guide.

Opensaas Sh Blog Src Content Docs Guides Seo Performance (`opensaas-sh/blog/src/content/docs/guides/seo-performance.mdx`) Copy Section

title: SEO & Performance
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

import { Image } from 'astro:assets';

This guides explains how to improve the SEO and performance for of your app.

Landing Page Meta Tags Copy Chapter

Wasp gives you the ability to add meta tags to your landing page HTML via the app's head property, defined in the src/client/head.wasp.ts file:

import { type App } from "@wasp.sh/spec";

export const head: App["head"] = [
  "<meta property='og:type' content='website' />",
  "<meta property='og:url' content='https://opensaas.sh' />",
  "<meta property='og:title' content='Open SaaS' />",
  "<meta property='og:description' content='Free, open-source SaaS boilerplate starter for React & NodeJS.' />",
  "<meta property='og:image' content='https://opensaas.sh/public-banner.webp' />",
  // ...
];

Change the above highlighted meta tags to match your app. Wasp will inject these tags into the HTML of your index.html file, which is the Landing Page (app/src/client/landing-page/LandingPage.tsx), in this case.

Prerendering Routes Copy Chapter

By default, a Wasp app is a Single Page Application (SPA). When someone visits your site, their browser first downloads a mostly empty page and then runs JavaScript to fill it in with the actual content. This works well for pages behind a login, but it has two downsides for pages like your landing page:

• Visitors wait longer before they see anything.
• Search engines and AI crawlers sometimes struggle to see your real content, which hurts your ranking.

Prerendering fixes both. You can turn it on for any route by adding prerender: true to its route definition:

route("LandingPageRoute", "/", page(LandingPage), { prerender: true }),

Now, when you run wasp build, Wasp builds a complete HTML version of that page ahead of time. Visitors (and Google) see your real content right away, and React still takes over in the background so buttons, links, and other interactions keep working as normal.

For a content-heavy landing page, this typically makes the page feel several times faster to load.

See the Wasp docs for the full reference and caveats: Prerendering.

:::tip[Star our Repo on GitHub! 🌟]
We've packed in a ton of features and love into this SaaS starter, and offer it all to you for free!

If you're finding this template and its guides useful, consider giving us a star on GitHub
:::

Structured Data (JSON-LD) Copy Chapter

In addition to meta tags, Open SaaS includes a SchemaMarkup component at src/landing-page/components/SchemaMarkup.tsx that embeds JSON-LD structured data into your landing page. This helps search engines and LLMs understand what your app is, who makes it, and what it offers, improving how it appears in search results, AI answers, and rich snippets.

const schema = {
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "SoftwareApplication",
      name: "Your Open SaaS App",
      description: "Your apps main description and features.",
      url: "https://your-saas-app.com",
      // ...
    },
  ],
};

Customize the schema object to match your product:

• Update name, description, and url
• Set applicationCategory / applicationSubCategory (see schema.org/SoftwareApplication)
• Add an Organization entry to associate the app with a company
• Add a FAQPage entry if your landing page has an FAQ section

The component is rendered inside LandingPage.tsx, and Wasp's prerendering inlines its output into the static HTML so crawlers see the structured data without needing to execute JavaScript.

AI / LLM Discoverability Copy Chapter

Beyond traditional search engines, AI assistants and LLM-powered search tools (ChatGPT, Perplexity, Claude, etc.) are an increasingly important source of discovery. The llms.txt convention provides a curated, markdown index of your site that these tools can use to understand and recommend your app.

The template ships a placeholder llms.txt at template/app/public/llms.txt, which gets served at https://your-saas-app.com/llms.txt:

# Your Open SaaS App

> One-line description of what your SaaS does and who it's for.

A longer paragraph giving context: the problem your app solves, the kind of
user it serves, and the key value it delivers.

## Core pages
- [Home](https://your-saas-app.com): Landing page with features, pricing, and FAQ
- [Pricing](https://your-saas-app.com/pricing): Subscription plans and pricing
- [Sign up](https://your-saas-app.com/signup): Create a new account

Customize it before deploying:

• Replace your-saas-app.com with your production URL
• Update the name, description, and longer paragraph to match your product
• Curate the list of links — include only your most important public pages
• Add or remove sections as needed (e.g. ## API, ## Integrations)

Keep the file short and intentional. It should be a concise index of your site that AI crawlers and LLMs can digest easily.

Docs & Blog Meta Tags Copy Chapter

Astro, being a static-site generator, will automatically inject relevant information provided in the blog/astro.config.mjs file, as well as in the frontmatter of .md files into the pages HTML:

---
title: 'My First Blog Post'
pubDate: 2022-07-01
description: 'This is the first post of my new Astro blog.'
author: 'Astro Learner'
image:
    url: 'https://docs.astro.build/assets/full-logo-light.png'
    alt: 'The full Astro logo.'
tags: ["astro", "blogging", "learning in public"]
---

Improving your SEO is as simple as adding these properties to your docs and blog content!

Opensaas Sh Blog Src Content Docs Guides Tests (`opensaas-sh/blog/src/content/docs/guides/tests.md`) Copy Section

title: Tests
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

This guide will show you how to use the included end-to-end (e2e) tests for your Open SaaS application.

The Tests Directory Copy Chapter

In the root of your project, you'll find an e2e-tests directory which contains the Playwright tests for your Open SaaS application:

.
├── e2e-tests/
│   ├── tests/                  # Directory containing the test files
│   ├── README.md               # Instructions on how to run the tests
│   ├── playwright.config.ts    # Playwright configuration
│   ├── package.json
│   ├── ...

To run the tests locally, or in a CI pipeline, follow the instructions in the README.md file in the e2e-tests directory.

Using Tests in CI with GitHub Actions Copy Chapter

Although the Open SaaS template does not come with an example GitHub workflow, you can find out how Open SaaS itself set it up in .github/workflows/e2e-tests.yml at Open SaaS repo.

You can copy and paste the .github/ directory containing the e2e-tests.yml workflow into the root of your own repository to run the tests as part of your CI pipeline.

:::caution[WASP_VERSION]
Please make sure to update the WASP_VERSION environment variable in the e2e-tests.yml file to match the version of Wasp you are using in your project.
:::

In order for these tests to run correctly on GitHub, you need to provide the environment variables mentioned in the e2e-tests.yml file within your GitHub repository's "Actions" secrets so that they can be accessed by the tests.

Opensaas Sh Blog Src Content Docs Guides Updating Opensaas (`opensaas-sh/blog/src/content/docs/guides/updating-opensaas.md`) Copy Section

title: How (Not) to Update Your Open SaaS App
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

:::danger[We advise against merging the latest template changes into your app]
If you've already started building your app, we generally advise against merging the latest template changes into your app.

Below we outline our reasoning why, and provide a basic guide to help you update your app if you decide to do so anyway.
:::

Why you probably shouldn't include the latest template changes in your app Copy Chapter

We generally advise against updating your Open SaaS-based applications after initial setup.

Why?

Because your codebase will naturally diverge from the template as you build your unique application, and any updates we may make to the template may not be compatible with your modified codebase, or your version of Wasp.

Even if you really want to include a new feature from the template in your app, proceed with caution and thoroughly consider the following:

• Changes to the template may be tightly coupled. Implementing one change without related ones could cause unexpected issues.
• Updates might not be compatible with your version of Wasp.
• The more your codebase has diverged, the more challenging the update will be.

If you still decide to update your app Copy Chapter

If you read above, considered the risks, and still need specific improvements, we recommend that you manually merge the changes.

To do this, you should can either 1) merge new Open SaaS template changes into your current project, or 2) merge project changes into a fresh Open SaaS template.

1. Merge new Open SaaS template changes into your current project by:

   • reviewing the latest commits,
   • understanding what happened,
   • being mindful of the Wasp version you're using,
   • and then fitting those changes into your own codebase.

2. Merge your project changes into a fresh Open SaaS template by:

   • starting a new, fresh project with the latest Open SaaS template,
   • and then copying over the logic from your existing project that you want to keep.

The method you choose is up to you and will largely depend on the complexity of the changes you need to make.

Opensaas Sh Blog Src Content Docs Guides Vibe Coding (`opensaas-sh/blog/src/content/docs/guides/vibe-coding.mdx`) Copy Section

title: "AI-assisted Coding / Vibe Coding with Open SaaS"
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

import { Image } from 'astro:assets';
import vibeBoi from '@assets/ai/vibe-boi.png';

If you're looking to use AI coding tools to help build your SaaS app, this guide is for you.

:::tip[New to building SaaS? Learn while you build with Open Vibe]
Open Vibe is our free, open-source curriculum that turns Claude Code (or your agent of choice) into a SaaS-building tutor. It pairs interactive diagrams with hands-on lessons — and Phase 2 builds a real SaaS on top of this very Open SaaS template.
:::

Coding with AI, Open SaaS, & Wasp Copy Chapter

Wasp is the perfect match for AI-assisted coding due to its central config file which gives LLMs immediate context about the entire full-stack app, as well as its ability to manage boilerplate code so AI doesn't have to.

To make it even easier, here are some resources to help you use Wasp & Open SaaS with AI as effectively as possible.

Agent Skills and Rules Copy Chapter

We've put some agent skills and rules into the template to help you get started using Open SaaS with your favorite AI-assisted coding tools (Claude Code, Cursor, VS Code/Copilot, Codex, Gemini CLI, OpenCode, etc.).

Skills are found in the app/.agents (and app/.claude) directory of the Open SaaS template, and follow the Agent Skills standard.
See your AI-assisted coding tool's documentation for more details on how to add Agent Skills if they don't load automatically.

Rules, found within the AGENTS.md (and CLAUDE.md), is another open standard used by many popular AI-assisted coding tools to give instructions to the agents when coding.

:::tip[These are just a starting point!]
Use these skills and rules to get your project up and running.

Run the add-wasp-skills skill to add Wasp framework-specific skills to your project for even more power.
:::

LLM-Friendly Documentation Copy Chapter

Note: the AGENTS.md has specific instructions on how to automatically fetch and use the LLM-friendly documentation but you can also paste the following links in chat sessions if needed.

• Open SaaS Docs - LLMs.txt - Links to the raw text docs.
• Open SaaS Docs - LLMs-full.txt - Complete docs as one text file.
• Wasp Docs - LLMs.txt - Links to the raw text docs by Wasp version.
• Wasp Docs - LLMs-full.txt - Complete docs as one text file.

More AI-assisted Coding Learning Resources Copy Chapter

Here's a list of articles and tutorials we've made:

• Open Vibe: a free, agent-guided curriculum for building your SaaS on Open SaaS
• 3hr YouTube tutorial: Vibe Coding a Personal Finance App w/ Wasp & Cursor
• Article: A Structured Workflow for "Vibe Coding" Full-Stack Apps

Opensaas Sh Blog Src Content Docs Start Guided Tour (`opensaas-sh/blog/src/content/docs/start/guided-tour.md`) Copy Section

title: Guided Tour
banner:
content: |
Have an Open SaaS app in production? We'll send you some swag! 👕

Awesome, you now have your very own SaaS app up and running! But, first, here are some important things you need to know about your app in its current state:

1. When signing up with a new user, you will get a message to check your email for a verification link. But, in development, these emails are simply written to your terminal. So, to continue with the registration process, check your server logs after sign up!

[ Server ] ╔═══════════════════════╗
[ Server ] ║ Dummy email sender ✉️  ║
[ Server ] ╚═══════════════════════╝
[ Server ] From:    Open SaaS App <[email protected]>
[ Server ] To:      [email protected]
[ Server ] Subject: Verify your email
[ Server ] ═════════ Text ═════════
[ Server ] Click the link below to verify your email: http://localhost:3000/email-verification?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InZpbm55QHdhc3Auc2giLCJleHAiOjE3MTg5NjUyNTB9.PkRGrmuDPuYFXkTprf7QpAye0e_O9a70xbER6LfxGJw
[ Server ] ═════════ HTML ═════════
[ Server ] <p>Click the link below to verify your email</p>
[ Server ] <a href="http://localhost:3000/email-verification?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InZpbm55QHdhc3Auc2giLCJleHAiOjE3MTg5NjUyNTB9.PkRGrmuDPuYFXkTprf7QpAye0e_O9a70xbER6LfxGJw">Verify email</a> 
[ Server ] ════════════════════════

2. Your app is still missing some key configurations (e.g. API keys for Payment Processors, OpenAI, AWS S3, Auth, Analytics). These services won't work at the moment, but don't fear, because we've provided detailed guides in these docs to help you set up all the services in this template.
3. If you want to get a feel for what your SaaS could look like when finished, check out OpenSaaS.sh in your browser. It was built using this template! So make sure to log in, play around with the demo app, make a test payment, and check out the admin dashboard.

In the sections below, we will take a short guide through the codebase and the app's main features. Then at the end of this tour, we also prepared a checklist of likely changes you will want to make to the app to make it your own.

We're looking forward to seeing what you build!

Getting acquainted with the codebase Copy Chapter

Now that you've gotten a first look at the app, let's dive into the codebase.

At the root of our project, you will see three folders:

.
├── app
├── blog
└── e2e-tests

app contains the Wasp project files, which is your full-stack (React + NodeJS + Prisma) app along with a Wasp Spec file, main.wasp.ts, which will be explained in more detail below.

blog contains the Astro Starlight theme for the blog and documentation section.

e2e-tests contains the end-to-end tests using Playwright, which you can run to test your app's functionality.

App File Structure Copy Section

We've structured this full-stack app template vertically (by feature). That means that most directories within app/src contain both the React client code and NodeJS server code necessary for implementing its logic.

Let's check out what's in the app folder in more detail:

.
├── main.wasp.ts           # Wasp Spec file. You define your app structure here.
├── schema.prisma          # Prisma schema file. You define your database models here.
├── .wasp/                 # Output dir for Wasp. DON'T MODIFY THESE FILES!
├── public/                # Public assets dir, e.g. `www.yourdomain.com/public-banner.webp`.
├── src/                   # Your code goes here.
│   ├── admin/             # Admin dashboard related pages and components.
│   ├── analytics/         # Logic and background jobs for processing analytics.
│   ├── auth/              # All auth-related pages/components and logic.
│   ├── client/            # Shared components, hooks, landing page, and other client code (React).
│   ├── demo-ai-app/       # Logic for the example AI-powered demo app.
│   ├── file-upload/       # Logic for uploading files to S3.
│   ├── landing-page/      # Landing page related code
│   ├── payment/           # Logic for handling payments and webhooks.
│   ├── server/            # Scripts, shared server utils, and other server-specific code (NodeJS).
│   ├── shared/            # Shared constants and util functions.
│   └── user/              # Logic related to users and their accounts.
├── .env.server            # Dev environment variables for your server code.
├── .env.client            # Dev environment variables for your client code.
├── .prettierrc            # Prettier configuration.
├── package.json
├── package-lock.json
└── .wasproot

The Wasp Config file Copy Section

This template at its core is a Wasp project, where Wasp is a full-stack web app framework that let's you write your app in React, NodeJS, and Prisma and will manage the "boilerplatey" work for you, allowing you to just take care of the fun stuff!

Wasp's secret sauce is its use of a config file, the Wasp Spec (main.wasp.ts), and compiler which takes your code and outputs the client app, server app and deployment code for you.

Because the Wasp Spec is just TypeScript, we've split the config vertically as well: each feature folder has its own *.wasp.ts file (e.g. src/auth/auth.wasp.ts, src/payment/payment.wasp.ts) which exports a Spec, and main.wasp.ts combines them all in the app definition:

import { app, page, route } from "@wasp.sh/spec";

import { LandingPage } from "./src/landing-page/LandingPage" with { type: "ref" };

import { authConfig, authSpec } from "./src/auth/auth.wasp";
import { paymentSpec } from "./src/payment/payment.wasp";
// ...

export default app({
  name: "OpenSaaS",
  wasp: { version: "^0.26.0" },
  title: "My Open SaaS App",
  auth: authConfig,
  // ...
  spec: [
    route("LandingPageRoute", "/", page(LandingPage), { prerender: true }),
    authSpec,
    paymentSpec,
    // ...
  ],
});

In this template, we've already defined a number of things in the Wasp Spec, including:

• Auth.
• Routes and Pages.
• Prisma Database Models.
• Operations (data read and write functions).
• Background Jobs.
• Email Sending.

By defining these things in the config file, Wasp continuously handles the boilerplate necessary with putting all these features together. You just need to focus on the business logic of your app.

Wasp abstracts away some things that you would normally be used to doing during development, so don't be surprised if you don't see some of the things you're used to seeing.

:::note
It's possible to learn Wasp's feature set simply through using this template, but if you find yourself unsure how to implement a Wasp-specific feature and/or just want to learn more, a great starting point is the intro tutorial in the Wasp docs which takes ~20 minutes.
:::

Client Copy Section

The src/client folder contains any additional client-side code that doesn't belong to a feature:

.
└── client
    ├── components         # Your shared React components.
    ├── hooks              # Your shared React hooks.
    ├── static             # Assets that you need access to in your code, e.g. import logo from 'static/logo.png'.
    ├── App.tsx            # Main app component to wrap all child components. Useful for global state, navbars, etc.
    ├── Main.css           # Main CSS file. Includes the Tailwind CSS into the project.
    └── utils.ts

Server Copy Section

The src/server folder contains any additional server-side code that does not belong to a specific feature:

└── server
    ├── scripts            # Scripts to run via Wasp, e.g. database seeding.
    └── validation.ts

Main Features Copy Chapter

Auth Copy Section

This template comes with a fully functional auth flow out of the box. It takes advantages of Wasp's built-in Auth features, which do the dirty work of rolling your own full-stack auth for you!

export const authConfig: Auth = {
  userEntity: "User",
  methods: {
    email: emailAuthMethod,
    google: googleAuthMethod,
    gitHub: gitGubAuthMethod,
    discord: discordAuthMethod,
  },
  onAuthFailedRedirectTo: "/login",
  onAuthSucceededRedirectTo: "/demo-app",
};

By defining the auth structure in the Wasp Spec, Wasp manages all the necessary code for you, including:

• Email verified login with password reset.
• Social login with Google and/or GitHub.
• Auth-related database entities for user credentials, sessions, and social logins.
• Custom-generated AuthUI components for login, signup, and password reset.
• Auth hooks for fetching user data.

We've set the template up with Wasp's email, google, discord and gitHub methods, which are all battle-tested and suitable for production.

You can get started developing your app with the email method right away!

:::caution[Dummy Email Provider]
Note that the email method relies on an emailSender (configured in the src/server/emailSender.wasp.ts file), a service which sends emails to verify users and reset passwords.

For development purposes, Wasp provides a Dummy email sender which Open SaaS comes with as the default. This provider does not actually send any confirmation emails to the specified email address, but instead logs all email verification links/tokens to the console! You can then follow these links to verify the user and continue with the sign-up process.

export const emailSender: EmailSender = {
  provider: "Dummy", // Logs all email verification links/tokens to the server's console.
  defaultFrom: {
    name: "Open SaaS App",
    email: "[email protected]",
  },
};

:::

We will explain more about these auth methods, and how to properly integrate them into your app, in the Authentication Guide.

Subscription Payments with Stripe, Lemon Squeezy or Polar Copy Section

No SaaS is complete without payments, specifically subscription payments. That's why this template comes with a fully functional Stripe, Lemon Squeezy and Polar integration.

Let's take a quick look at how payments are handled in this template.

1. A user clicks the BUY button and a checkout session is created on the server.
2. The user is redirected to the payment processor's checkout page where they enter their payment info.
3. The checkout session is completed and the user is redirected back to the app.
4. Payment processor sends a webhook event to the app's server with the payment info.
5. The app server's webhook handler handles the event and updates the user's subscription status.

The payment processor you choose (Stripe, Lemon Squeezy, Polar or Paddle) and its related functions can be found at src/payment/paymentProcessor.ts. The PaymentProcessor object holds the logic for creating checkout sessions, webhooks, etc. Its client-side counterpart, PaymentProcessorClient in src/payment/paymentProcessorClient.ts, opens the checkout session in the browser.

The logic for creating the Checkout session is defined in the src/payment/operation.ts file. Actions are a type of Wasp Operation, specifically your server-side functions that are used to write or update data to the database. Once they're defined in the Wasp Spec, you can easily call them on the client-side:

a) define the action in the src/payment/payment.wasp.ts file

import { action, type Spec } from "@wasp.sh/spec";
import { generateCheckoutSession } from "./operations" with { type: "ref" };

export const paymentSpec: Spec = [
  // ...
  action(generateCheckoutSession, { entities: ["User"] }),
];

b) implement the action in the src/payment/operations file

export const generateCheckoutSession: GenerateCheckoutSession<
  GenerateCheckoutSessionInput,
  CheckoutSession
> = async (rawPaymentPlanId, context) => {
  // ...
};

c) call the action on the client-side

import { generateCheckoutSession } from "wasp/client/operations";

async function handleBuyNowClick(paymentPlanId: PaymentPlanId) {
  // ...
  const checkoutSession = await generateCheckoutSession(paymentPlanId);
  // ...
};

The webhook handler is defined in the src/payment/webhook.ts file. Unlike Actions and Queries in Wasp which are only to be used internally, we define the webhook handler in the Wasp Spec as an API endpoint in order to expose it externally to the payment processor.

import { api, type Spec } from "@wasp.sh/spec";
import { paymentsMiddlewareConfigFn, paymentsWebhook } from "./webhook" with { type: "ref" };

export const paymentSpec: Spec = [
  // ...
  api("POST", "/payments-webhook", paymentsWebhook, {
    entities: ["User", "ProcessedWebhookEvent"],
    middlewareConfigFn: paymentsMiddlewareConfigFn,
  }),
];

Within the webhook handler, we look for specific events that the payment processor sends us to let us know which payment was completed and for which user. Then we update the user's subscription status in the database.

Payment processors can deliver the same event more than once, for example when they retry after a timeout. The webhook handler records the id of every processed event in the ProcessedWebhookEvent entity and skips the events it has already seen, so a retried event can't grant purchased credits twice. You can find this logic in src/payment/processedWebhookEvent.ts.

To learn more about configuring the app to handle your products and payments, check out the Payment Integrations guide.

:::tip[Star our Repo on GitHub! 🌟]
We've packed in a ton of features and love into this SaaS starter, and offer it all to you for free!

If you're finding this template and its guides useful, consider giving us a star on GitHub
:::

Analytics and Admin Dashboard Copy Section

Keeping an eye on your metrics is crucial for any SaaS. That's why we've built an administrator's dashboard where you can view your app's stats, user data, and revenue all in one place.

To do that, we've leveraged Wasp's Jobs feature to run a cron job that calculates your daily stats. The app stats, such as page views and sources, can be pulled from either Plausible or Google Analytics. All you have to do is create a project with the analytics provider of your choice and import the respective pre-built helper functions!

import { job, type Spec } from "@wasp.sh/spec";
import { calculateDailyStatsJob } from "./stats" with { type: "ref" };

export const analyticsSpec: Spec = [
  // ...
  job(calculateDailyStatsJob, {
    executor: "PgBoss",
    schedule: {
      cron: "0 * * * *", // Every hour. useful in production.
      // cron: "* * * * *" // Every minute. useful for debugging.
    },
    entities: ["User", "DailyStats", "Logs", "PageViewSource"],
  }),
];

For more info on integrating Plausible or Google Analytics, check out the Analytics guide.

SEO & Discoverability Copy Section

Open SaaS ships SEO-friendly out of the box. Three pieces work together so your app shows up in search results and AI answers:

1. Meta tags in the app's head config (src/client/head.wasp.ts) — title, description, Open Graph, Twitter cards — get injected into your landing page HTML.
2. JSON-LD structured data (Schema Markup) in src/landing-page/components/SchemaMarkup.tsx tells search engines and LLMs what your app is, who makes it, and what it offers — feeding rich snippets and AI-generated answers.
3. Prerendering turns your React marketing pages (e.g. landing page, pricing, FAQ, etc.) into static HTML at build time, so crawlers see your content (including the schema markup) without needing to execute JavaScript.

Customize the meta tags in src/client/head.wasp.ts and the schema object in SchemaMarkup.tsx to match your product. See the SEO guide for details.

App Customization Walkthrough Copy Chapter

General Considerations Copy Section

When you first start your Open SaaS app straight from the template, it will run, but many of the services won't work because they lack your own API keys. Here are list of services that need your API keys to work properly:

• Auth Methods (Google, Discord, GitHub).
• Payment processor (Stripe, Lemon Squeezy or Polar).
• OpenAI (ChatGPT API).
• Email Sending (Sendgrid) -- you must set this up if you're using the email auth method.
• Analytics (Plausible or Google Analytics).
• File Uploading (AWS S3).

Now would be a good time to decide which features you do and do not need for your app, and remove the ones from the codebase that you don't need.

For the features you will use, the next section of the documentation, Guides, will walk you through how to set each one up!

:::note[Open SaaS is built on Wasp]
Remember, this template is built on the Wasp framework. If, at any time, these docs fail to provide enough information about a certain built-in feature, make sure to check out the Wasp docs!
:::

But before you start setting up the main features, let's walk through the customizations you will likely want to make to the template to make it your own.

Customizations Checklist Copy Section

Wasp Spec (`main.wasp.ts`)

• Change the app name and title:

  ts title="main.wasp.ts" {2, 4} Copy

  export default app({
    name: "YourAppName",
    wasp: { version: "^0.26.0" },
    title: "Your App Name",
    // ...
  });

  :::caution[Restart Your App]
  Development databases are connceted to your app's name. Upon changing the app name, new, empty development database will be assigned to your app. This means you'll need to rerun wasp db start, wasp db migrate-dev and wasp start.
  :::

• Update meta tags in the head config (src/client/head.wasp.ts) (even if you don't have a custom domain yet, put one you would like to have, as this won't affect development).

• Update defaultFrom.name in the emailSender config (src/server/emailSender.wasp.ts) with the name of your app/company/whatever you want your users to see in their inbox, if you're using the emailSender feature and/or email Auth method.

• Remove any features you might not use or need:

  • Auth methods - methods in src/auth/auth.wasp.ts:
    • If you're not using email Auth method, remove the routes/pages: RequestPasswordReset, PasswordReset, and EmailVerification.
  • Email Sending - src/server/emailSender.wasp.ts.
  • Plausible analytics - head config in src/client/head.wasp.ts.
  • File Uploading - the File model in schema.prisma, the src/file-upload/file-upload.wasp.ts spec, and all operations tied to file uploading.

• Rename Entites and their properties, Routes/Pages, & Operations, if you wish.

Customizing the Look / Style of the App

• Update your favicon at public/favicon.ico.
• Update the banner image used when posting links to your site at public/public-banner.webp.
  • Update the URL for this banner at og:image and twitter:image in the head config of the src/client/head.wasp.ts file.
• Update the JSON-LD structured data in src/landing-page/components/SchemaMarkup.tsx with your app's name, description, URL, and other metadata. This helps search engines and LLMs understand your app for rich results and AI answers.
• Make changes to your landing page, LandingPage.tsx.
  • Customize the navBar, features, testimonials, and faqs in the contentSections.ts file.
  • Change/rename the logo.webp and main hero banner (open-saas-banner.webp) in the static folder.
• If you want to make changes to the global styles of the app, you can do so in Main.css. Be aware that changing the current global styles affects most of the app!

Customizing the Analytics & Admin Dashboard

• If you're using Plausible, update the head config in src/client/head.wasp.ts with your Plausible domain.
• Update the calculateDailyStatsJob function in src/analytics/stats.ts to pull the stats from the analytics provider you've chosen (Plausible or Google Analytics).
• Change the cron schedule of the calculateDailyStatsJob in the src/analytics/analytics.wasp.ts file to match how often you want your stats to be calculated.
• Update the AdminDashboard components to display the stats you do/don't want to see.

`.env.server` and `.env.client` Files

• After you've followed the Guides in the next section, you'll need to update the .env.server and .env.client files with your API keys and other environment variables for the services you've decided to use.
• Delete any redundant environment variables that you're not using, from the .env.* files as well as the .env.*.example files.

Other Customizations

• Make a new GitHub repository for your app.
• Deploy your app to a hosting provider.
• Buy a domain name for your app and get it set up with your hosting provider.
• Read the e2e-tests README and get your end-to-end tests set up.
  • Change the tests to suit the changes you've made to your app.
• Get the CI pipeline set up for your app (you can get started by using the Open SaaS development CI example here).

What's next? Copy Chapter

In the following Guides sections, we'll walk you through getting those API keys and setting up the finer points of features such as Payments & Webhooks, Auth, Email Sending, Analytics, and more.

Template Blog Src Content Docs Blog 2023 11 21 Coverlettergpt (`template/blog/src/content/docs/blog/2023-11-21-coverlettergpt.md`) Copy Section

title: How I Built & Grew CoverLetterGPT to 5,000 Users and $200 MRR
date: 2023-11-21
tags: ["indiehacker", "saas", "sideproject"]
subtitle: A guide to building a profitable, open-source side-project
hideBannerImage: false # Banner images stored in public/banner-images/ are automatically used as cover images and social media preview images (og:image) for each blog post.
authors:

• name: vince
  title: Dev Rel @ Wasp
  url: https://wasp.sh

Hey, I’m Vince… Copy Chapter

I’m a self-taught developer that changed careers during the Covid Pandemic. I did it because I wanted a better career, enjoyed programming, and at the same time, had a keen interest in IndieHacking.

If you’re not aware, IndieHacking is the movement of developers who build potentially profitable side-projects in their spare time. And there are some very successful examples of IndieHackers and “solopreneurs” out there inspiring others, such as levels.io and Marc Lou.

This thought of being able to build my own side-project that could generate profit while I slept was always attractive to me.

So I’m happy to report that I’ve finally done it with my first software-as-a-service (SaaS) app, CoverLetterGPT.xyz, which I launched in March 2023!

I’ll be the first to admit that the results aren’t spectacular, but they’re still something I’m very proud of:

• over 5,000 registered users
• $203 monthly recurring revenue (MRR)

Below, I’m going to share with you how I built it (yes, it’s open-source!), how I marketed and monetized it, along with a bunch of helpful resources to help you build your own profitable side-project.

What the heck is CoverLetterGPT? Copy Chapter

CoverLetterGPT.xyz was an idea I got after the OpenAI API was released. It’s an app that allows you to upload a PDF of your CV/resumé, along with the job description you’re applying to, and it will generate and edit unique cover letters for you based on this information.

{% embed https://youtu.be/ZhcFRD9cVrI %}

It also lets you save and manage your cover letters per each job, making it easy to make and apply to multiple jobs without having to keep copy and pasting all your important info into ChatGPT!

What’s the Tech Stack? Copy Chapter

CoverLetterGPT is entirely open-source, so you can check out the code, fork it, learn from it, make your own, submit a PR (I’d love you forever if you did 🙂)… whatever!

I built it using the Wasp full-stack framework which allowed me to ship it about 10x faster.

Why?

Because Wasp as a framework allows you to describe your app’s core features in a main.wasp config file. Then it continually compiles and “glues” these features into a React-ExpressJS-Prisma full-stack app for you.

All you have to focus on is writing the client and server-side logic, and Wasp will do the boring stuff for you, like authentication & authorization, server config, email sending, and cron jobs.

BTW, Wasp is open-source and free and you can help the project out a ton by starring the repo on GitHub: https://www.github.com/wasp-lang/wasp 🙏

{% cta https://www.github.com/wasp-lang/wasp %} ⭐️ Thanks For Your Support 🙏 {% endcta %}

For the UI, I used Chakra UI, as I always do. I like that it’s a component-based UI library. This helps me build UI’s a lot faster than I would with Tailwind or vanilla CSS.

For payments, I used Stripe, (I’ll go into the details of monetization below).

The Server and Postgres Database are hosted on https://railway.app, with the client on Netlify.com’s free tier.

By the way, If you’re interested in building your own SaaS with almost the same stack as above, I also built a free SaaS template you can use that will save you days of work!

How I Marketed It Copy Chapter

My biggest take-away from this whole project was that open-sourcing it was the best way to market it!

This seems counter-intuitive, right? Why would making the code available for anyone to see and copy be good for a business? You’re basically rolling out a red carpet for competitors, aren’t you?

Well, not quite.

First of all, the number of people who will realistically spend the time and energy launching a direct competitor is low. Also, most people interested in your open-source code want to learn some aspect of it and apply it to their own ideas, not just copy yours directly.

Secondly, and most importantly, the fact that it’s open-source makes people a lot more receptive to you talking about it.

When you present something you’ve built and give people the opportunity to learn from it, they’re much more welcoming! As a result, they’re more likely to upvote it, share it, use it, and recommend it to others.

This is exactly what happened with CoverLetterGPT! As a result of me sharing the open-source code, it get featured on the IndieHackers.com newsletter (>100k subscribers), shared on blogs, and talked about on social media platforms.

And even though it’s a small, simple product, I tried launching it on Product Hunt, where it also performed considerably well.

So, all together, these initial efforts combined gave my product a good initial marketing presence. To this day, I haven’t really done much else to market it, except some twitter posts (and this post, if you want to consider it marketing 🤑).

How I Monetized It Copy Chapter

When I first launched in March 2023, I didn’t really expect anyone to pay for the product, but I wanted to learn how to use Stripe as a payments processor, thinking that the skills might be useful in the future.

So I started simple, and just put a one-time payment link for tips. No paywall, no subscriptions. It was entirely free to use with any tip amount welcome.

To my surprise, tips started coming in, with some as high as $10 dollars!

This encouraged me to force users to login to use the product, and add a paywall after users used up 3 credits.

My initial payment options were:

• $4.95 for a 3 months access
• $2.95 for 10 cover letter generations

That went reasonably well until I implemented the ability for users to use GPT to make finer edits to their generated cover letters. That’s when I changed my pricing and that’s when better profits started to come in:

• $5.95 / month subscription with GPT-4
• $2.95 / month subscription with GPT-3.5-turbo

Currently, over 90% of my customers choose the more powerful, more expensive plan with GPT-4, even though the 3 trial credits use the GPT-3.5-turbo model.

(I also integrated Bitcoin Lightning payments — check out the repo if you want to learn how — but haven’t received any yet.)

Now, with an MRR of ~$203, my monthly profit of course depends on my costs, which are:

• Domain Name: $10/year
• OpenAI bill: ~ $15/month
• Hosting bill: ~ $3/month

Which leaves me at about ~ $183/month in profits 😀

Future Plans Copy Chapter

One of the most surprising aspects about CoverLetterGPT.xyz’s success is that, on the surface, the product is very simple. Also, I’ve done very little in the way of SEO marketing, and haven’t continued to market it much at all. The current growth is mostly organic at this point thanks to my initial marketing efforts.

But I still have some plans to make it better:

• buy a better top-level domain (TLD), like CoverLetterGPT.ai
• add more features, like the ability to generate interview questions based on the cover letters
• improve the UX and make it look more “professional”

If you have any other ideas how I could improve it, drop me a comment, message me on twitter/x, or submit a PR to the repo.

Final Words + More Resources Copy Chapter

My intention with this article was to help others who might be considering launching their own SaaS product. So I hope that’s been the case here. If you still have any questions, don’t hesitate to ask.

Here are also the most important links from this article along with some further resources that will help in building and marketing your own profitable side-project:

• 👨‍💻 CoverLetterGPT GitHub Repo
• 💸 Free Full-Stack SaaS Template w/ Google Auth, Stripe, GPT, & instructions in the README!
• ✍️ Initial CoverLetterGPT Reddit Post
• 🪓 IndieHackers Feature
• 💸 Great Video on how to use Stripe CLI & Webhooks

Oh, and if you found these resources useful, don't forget to support Wasp by starring the repo on GitHub!

{% cta https://www.github.com/wasp-lang/wasp %} ⭐️ Thanks For Your Support 🙏 {% endcta %}

Template Blog Src Content Docs Blog 2023 11 23 Post (`template/blog/src/content/docs/blog/2023-11-23-post.md`) Copy Section

title: My first blog post date: 2023-11-20 tags: ["blog", "post", "saas", "rocknroll"] authors: ["Dev"] Copy Chapter

Hello Copy Chapter

Hello world!

Template Blog Src Content Docs Guides Example (`template/blog/src/content/docs/guides/example.md`) Copy Section

title: Example Guide Copy Chapter

This is an example guide. It's a good idea to have a guide for each major feature of your project. Guides should be short and to the point. They should also be written in a way that is easy to understand for beginners.

Example Heading Copy Chapter

...

Opensaas Sh Blog Src Content Docs 0.23 General Admin Dashboard (`opensaas-sh/blog/src/content/docs/0.23/general/admin-dashboard.mdx`) Copy Section

title: Admin Dashboard
banner:
content: >
Have an Open SaaS app in production? We'll send you some
swag! 👕

slug: 0.23/general/admin-dashboard Copy Chapter

import adminDashboard from '@assets/admin/admin-dashboard.png';
import dbStudio from '@assets/stripe/db-studio.png';
import { Image } from 'astro:assets';

This is a reference on how the Admin dashboard, available at /admin, is set up.

Permissions Copy Chapter

The Admin dashboard is only accessible to users with the isAdmin field set to true.

model User {
  id                        String          @id @default(uuid())
  createdAt                 DateTime        @default(now())

  email                     String?         @unique
  username                  String?         @unique
  isAdmin                   Boolean         @default(false)
  //...

To give yourself administrator priveledges, make sure you add your email addresses to the ADMIN_EMAILS environment variable in .env.server file before registering/logging in with that email address:

[email protected]

// or add many admins with a comma-separated list

[email protected],[email protected],[email protected]

Or if you've already logged in with an email address that you want to give admin priveledges to, you can run the following command in a separate terminal window to update the user's isAdmin field manually:

wasp db studio

:::tip[Star our Repo on GitHub! 🌟]
We've packed in a ton of features and love into this SaaS starter, and offer it all to you for free!

If you're finding this template and its guides useful, consider giving us a star on GitHub
:::

Admin Dashboard Pages Copy Chapter

Analytics Dashboard Copy Section

The Admin analytics dashboard is a single place for you to view your most important metrics and perform some admin tasks. At the moment, it pulls data from:

• Payment Processor:
  • Total revenue.
  • Revenue for each day of the past week.
• Google or Plausible:
  • Total number of page views (non-unique).
  • Percentage change in page views from the previous day.
  • Top sources/referrers with unique visitor count (i.e. how many people came from that source to your app).
• Database:
  • Total number of registered users.
  • Daily change in number of registered users .
  • Total number of paying users.
  • Daily change in number of paying users.

These metrics are aggregated within the background job dailyStatsJob, which by default is run every hour. You can change the frequency of this job by modifying its cron field:

job dailyStatsJob {
  executor: PgBoss,
  perform: {
    fn: import { calculateDailyStats } from "@src/analytics/stats"
  },
  schedule: {
    cron: "0 * * * *" // Every hour. useful in production.
    // cron: "* * * * *" // Every minute. useful for debugging.
  },
  entities: [User, DailyStats, Logs, PageViewSource]
}

For more info on Wasp's recurring background jobs, check out the Wasp Jobs docs.

For a guide on how to integrate these services so that you can view your analytics via the dashboard, check out the Payment Integrations and Analytics guide of the docs.

:::note[Help us improve]
We're always looking to improve the Admin dashboard. If you feel something is missing or could be improved, consider opening an issue or submitting a pull request
:::

Users Copy Section

The Users page is where you can view all your users and their most important details. You can also search and filter users by:

• Email address.
• Subscription/payment status.
• Admin status.

Opensaas Sh Blog Src Content Docs 0.23 General Privacy Policy (`opensaas-sh/blog/src/content/docs/0.23/general/privacy-policy.mdx`) Copy Section

title: Privacy Policy sidebar: hidden: true slug: 0.23/general/privacy-policy Copy Chapter

OpenSaaS.sh

Last updated: 2026-01-13

OpenSaaS.sh ("we", "our", or "us") is committed to protecting your privacy. This Privacy Policy explains how we collect, use, disclose, and safeguard your information when you visit our website (https://opensaas.sh).

Please read this privacy policy carefully. If you do not agree with the terms of this privacy policy, please do not access the site.

What Data Do We Collect? Copy Chapter

OpenSaaS.sh collects the following types of personal data:

• IP address
• browser type
• pages visited
• time spent on pages

How Do We Collect Your Data? Copy Chapter

You directly provide OpenSaaS.sh with most of the data we collect. We collect data and process data when you:

• Use or view our website via your browser's cookies.

How Will We Use Your Data? Copy Chapter

OpenSaaS.sh collects your data so that we can:

• Analyze website traffic
• Improve our website
• Understand how visitors use our site

Third-Party Services Copy Chapter

We use third-party services to help us operate our website, conduct our business, and provide services to you. These services may collect information about your visit to our website.

We use the following third-party services:

• Google Analytics
• REO.dev

These third-party service providers have their own privacy policies addressing how they use your information. We encourage you to review their privacy policies.

We only share information with these parties as necessary to provide our services to you, and they are obligated to keep your information confidential and secure.

How Do We Store Your Data? Copy Chapter

OpenSaaS.sh securely stores your data using industry-standard security measures.

Security Measures Copy Section

We implement the following security measures to protect your data:

• SSL/TLS encryption
• Secure cloud infrastructure

Data Retention Copy Section

OpenSaaS.sh will keep your personal data for as long as necessary to fulfill the purposes outlined in this privacy policy. Once this period has expired, we will delete your data securely.

Marketing Copy Chapter

OpenSaaS.sh would like to send you information about products and services of ours that we think you might like.

If you have agreed to receive marketing, you may always opt out at a later date. You have the right at any time to stop OpenSaaS.sh from contacting you for marketing purposes.

If you no longer wish to be contacted for marketing purposes, please contact us at [email protected].

Your Data Protection Rights Copy Chapter

OpenSaaS.sh would like to make sure you are fully aware of all of your data protection rights. Every user is entitled to the following:

The right to access – You have the right to request copies of your personal data. We may charge you a small fee for this service.

The right to rectification – You have the right to request that we correct any information you believe is inaccurate. You also have the right to request that we complete information you believe is incomplete.

The right to erasure – You have the right to request that we erase your personal data, under certain conditions.

The right to restrict processing – You have the right to request that we restrict the processing of your personal data, under certain conditions.

The right to object to processing – You have the right to object to our processing of your personal data, under certain conditions.

The right to data portability – You have the right to request that we transfer the data that we have collected to another organization, or directly to you, under certain conditions.

If you make a request, we have one month to respond to you. If you would like to exercise any of these rights, please contact us at:

• Email: [email protected]

Cookies Copy Chapter

Cookies are text files placed on your computer to collect standard Internet log information and visitor behavior information. When you visit our website, we may collect information from you automatically through cookies or similar technology.

For further information, visit allaboutcookies.org.

How Do We Use Cookies? Copy Section

OpenSaaS.sh uses cookies in a range of ways to improve your experience on our website, including:

• Functional cookies: Keeping you signed in and remembering your preferences
• Analytics cookies: Understanding how you use our website to improve our services

Managing Cookies Copy Section

You can set your browser not to accept cookies, and the website allaboutcookies.org tells you how to remove cookies from your browser. However, in a few cases, some of our website features may not function as a result.

Privacy Policies of Other Websites Copy Chapter

Our website may contain links to other websites. Our privacy policy applies only to our website, so if you click on a link to another website, you should read their privacy policy.

Changes to Our Privacy Policy Copy Chapter

OpenSaaS.sh keeps its privacy policy under regular review and places any updates on this web page. This privacy policy was last updated on 2026-01-13.

How to Contact Us Copy Chapter

If you have any questions about OpenSaaS.sh's privacy policy, the data we hold on you, or you would like to exercise one of your data protection rights, please do not hesitate to contact us at:

• Email: [email protected]

How to Contact the Appropriate Authority Copy Chapter

Should you wish to report a complaint or if you feel that OpenSaaS.sh has not addressed your concern in a satisfactory manner, you may contact your local data protection supervisory authority.

This privacy policy is based on the GDPR privacy policy template from GDPR.eu.

Opensaas Sh Blog Src Content Docs 0.23 Guides Analytics (`opensaas-sh/blog/src/content/docs/0.23/guides/analytics.md`) Copy Section

title: Analytics
banner:
content: >
Have an Open SaaS app in production? We'll send you some
swag! 👕

slug: 0.23/guides/analytics Copy Chapter

This guide will show you how to integrate analytics for your app. You can choose between Google Analytics and Plausible.

Google Analytics is free, but uses cookies, so you'll probably want/need to implement the Cookie Consent Modal when using it.

Plausible is an open-source, privacy-friendly alternative to Google Analytics. You DO NOT have to use the cookie consent modal with Plausible, as it does not use cookies. It's also easier to use than Google if you use their hosted service, but be aware it is a paid feature. It is completely free if you want to self-host it, although this comes with some additional setup steps.

If you're looking to add analytics to your blog, you can follow the Adding Analytics to your Blog section at the end of this guide.

Plausible Copy Chapter

Hosted Plausible Copy Section

Sign up for a hosted Plausible account here.

Once you've signed up, you'll be taken to your dashboard. Create your site by adding your domain. Your domain is also your PLAUSIBLE_SITE_ID in your .env.server file. Make sure to add it.

PLAUSIBLE_SITE_ID=<your domain without www>

After adding your domain, you'll be taken to a page with your Plausible script tag. Copy and paste this script tag into the main.wasp file's head section.

app OpenSaaS {
  wasp: {
    version: "^0.23.0"
  },
  title: "My SaaS App",
  head: [
    "<your plausible script tag here>",
  ],
  //...

Go back to your Plausible dashboard, click on your username in the top right, and click on the Settings tab. Scroll down, find your API key and paste it into your .env.server file under the PLAUSIBLE_API_KEY variable.

:::note[No Cookies]
Plausible does not use cookies, so you don't need to add it to your Cookie Consent Modal, hence the script can be added directly to app.head in your main.wasp file.
:::

Self-hosted Plausible Copy Section

Plausible, being an open-source project, allows you to self-host your analytics. This is a great option if you want to keep your data private and not pay for the hosted service.

coming soon...

...until then, check out the official documentation.

:::tip[Contribute!]
If you'd like to help us write this guide, click the "Edit page" button at the bottom of this page

As a completely free, open-source project, we appreciate any help 🙏
:::

Google Analytics Copy Chapter

First off, head over to src/analytics/stats.ts and switch out the Plausible Provider for Google Analytics so that your background (cron) job fetches the data from Google Analytics for your Admin Dashboard:

//...
import { getDailyPageViews, getSources } from './providers/plausibleAnalyticsUtils';
import { getDailyPageViews, getSources } from './providers/googleAnalyticsUtils';

export const calculateDailyStats: DailyStatsJob<never, void> = async (_args, context) => { 
  //...
}

Next, make sure you sign up for Google analytics, then go to your Admin panel in the bottom of the left sidebar and then create a "Property" for your app.

Once you've created a new Property, some Installation Instructions will pop up. Select install manually where you should see a string that looks like this:

"">https://www.googletagmanager.com/gtag/js?id=<your-google-analytics-id>

and copy and paste the Google Analytics ID into your .env.client file to get it working with the Cookie Consent Modal provided with this template:

REACT_APP_GOOGLE_ANALYTICS_ID=<your-google-analytics-id> # e.g. G-1234567890

:::tip[noscript]
In the Installation Instructions, Google Tag Manager might also instruct you to paste the noscript code snippet immediately after the opening `` tag.
You should skip this step because this snippet is activated only if users try to browse your app without JavaScript enabled, which is very rare and React needs JS anyway.
:::

Then, set up the Google Analytics API access by following these steps:

1. Set up a Google Cloud project: If you haven't already, start by setting up a project in the Google Cloud Console.

2. Enable the Google Analytics API for your project: Navigate to the "Library" in the Google Cloud Console and search for the "Google Analytics Data API" (for Google Analytics 4 properties) and enable it.

3. Create credentials: Now go to the "Credentials" tab within your Google Cloud project, click on + credentials, and create a new service account key. First, give it a name. Then, under "Grant this service account access to project", choose viewer.

4. Create Credentials: When you go back to Credentials page, you should see a new service account listed under "Service Accounts". It will be a long email address to ends with @your-project-id.iam.gserviceaccount.com. Click on the service account name to go to the service account details page.

   • Under "Keys" in the service account details page, click "Add Key" and choose Create new key.

   • Select "JSON", then click "Create" to download your new service account's JSON key file. Keep this file secure and don't add it to your git repo as it grants access to your Google Analytics data.

5. Update your Google Anayltics Settings: Go back to your Google Analytics dashboard, and click on the Admin section in the left sidebar. Under Property Settings > Property > Property Access Management Add the service account email address (the one that ends with @your-project-id.iam.gserviceaccount.com) and give it Viewer permissions.

6. Encode and add the Credentials: Add the client_email and the private_key from your JSON Key file into your .env.server file. But be careful! Because Google uses a special PEM private key, you need to first convert the key to base64, otherwise you will run into errors parsing the key. To do this, in a terminal window, run the command below and paste the output into your .env.server file under the GOOGLE_ANALYTICS_PRIVATE_KEY variable:

   sh Copy

   echo -n "-----BEGIN PRIVATE KEY-----\nMI...A++eK\n-----END PRIVATE KEY-----\n" | base64

7. Add your Google Analytics Property ID: You will find the Property ID in your Google Analytics dashboard in the Admin > Property > Property Settings > Property Details section of your Google Analytics property (not your Google Cloud console). Add this 9-digit number to your .env.server file under the GOOGLE_ANALYTICS_PROPERTY_ID variable.

Adding Analytics to your Blog Copy Chapter

To add your analytics script to your Astro Starlight blog, all you need to do is modify the head property in your blog/astro.config.mjs file.

Below is an example of how to add Google Analytics to your blog:

export default defineConfig({
  site: 'https://opensaas.sh',
  integrations: [
    starlightBlog({ 
      // ...
    }),
    starlight({
      //...
       head: [
        {
          tag: 'script',
          attrs: {
            src: 'https://www.googletagmanager.com/gtag/js?id=<YOUR-GOOGLE-ANALYTICS-ID>',
          },
        },
        {
          tag: 'script',
          content: `
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());
        
          gtag('config', '<YOUR-GOOGLE-ANALYTICS-ID>');
          `,
        },
      ],

Opensaas Sh Blog Src Content Docs 0.23 Guides Authentication (`opensaas-sh/blog/src/content/docs/0.23/guides/authentication.md`) Copy Section

title: Authentication
banner:
content: >
Have an Open SaaS app in production? We'll send you some
swag! 👕

slug: 0.23/guides/authentication Copy Chapter

Setting up your app's authentication is easy with Wasp. In fact, it's already set up for you in the main.wasp file:

auth: {
    userEntity: User,
    methods: {
      email: {}, 
      google: {},
      gitHub: {},
      discord: {}
    },
    onAuthFailedRedirectTo: "/",
  },

The great part is, by defining your auth config in the main.wasp file, Wasp manages most of the Auth process for you, including the auth-related database entities for user credentials and sessions, as well as auto-generated client components for your app on the fly (aka AuthUI -- you can see them in use in the src/auth folder).

Email Verified Auth Copy Chapter

email method is the default auth method in Open SaaS.

Since it needs to send emails to verify users and reset passwords, it requires an email sender provider: a service it can use to send emails.
A "email sender" provider is configured via app.emailSender field in the main.wasp file.

:::caution[Dummy Email Provider]
To make it easy for you to get started, Open SaaS initially comes with the Dummy "email sender" provider, which does not send any emails, but instead logs all email verification links/tokens to the server's console!
You can then follow these links to verify the user and continue with the sign-up process.

emailSender: {
    provider: Dummy, // Logs all email verification links/tokens to the server's console.
    defaultFrom: {
      name: "Open SaaS App",
      email: "[email protected]" 
    },
  },

You can not use the Dummy provider in production and your app will not build until you move to a production-ready provider, such as SendGrid. We outline the process of migrating to SendGrid below.
:::

In order to use the email auth method in production, you'll need to switch from the Dummy "email sender" provider to a production-ready provider like SendGrid:

1. First, set up your app's emailSender in the main.wasp file by following this guide.
2. Add your SENDGRID_API_KEY to the .env.server file.
3. Make sure the email address you use in the fromField object is the same email address that you configured your SendGrid account to send out emails with. In the end, your main.wasp file should look something like this:

auth: {
    methods: {
      email: {
        fromField: {
          name: "Open SaaS App",
          // When using SendGrid, you must use the same email address that you configured your account to send out emails with!
          email: "[email protected]" 
        },
        //...
      }, 
    }
  },
  //...
  emailSender: {
    provider: Dummy,
    provider: SendGrid,
    defaultFrom: {
      name: "Open SaaS App",
      // When using SendGrid, you must use the same email address that you configured your account to send out emails with!
      email: "[email protected]" 
    },
  },

And that's it. Wasp will take care of the rest and update your AuthUI components accordingly.

Check out the Wasp Auth docs for more info.

Google, GitHub, & Discord Auth Copy Chapter

We've also customized and pre-built the Google, Discord and GitHub auth flow for you. To start using them, you just need to uncomment out the methods you want in your main.wasp file and obtain the proper API keys to add to your .env.server file.

To create a Google OAuth app and get your Google API keys, follow the instructions in Wasp's Google Auth docs.

To create a GitHub OAuth app and get your GitHub API keys, follow the instructions in Wasp's GitHub Auth docs.

To create a Discord OAuth app and get your Discord API keys, follow the instructions in Wasp's Discord Auth docs

Again, Wasp will take care of the rest and update your AuthUI components accordingly.

Opensaas Sh Blog Src Content Docs 0.23 Guides Authorization (`opensaas-sh/blog/src/content/docs/0.23/guides/authorization.md`) Copy Section

title: Authorization
banner:
content: >
Have an Open SaaS app in production? We'll send you some
swag! 👕

slug: 0.23/guides/authorization Copy Chapter

This guide will help you get started with authorization in your SaaS app.

Authorization refers to what users can access in your app. This is useful for differentiating between users who have paid for different subscription tiers (e.g. "hobby" vs "pro"), or between users who have admin privileges and those who do not.

Authorization differs from authentication in that authentication refers to the process of verifying that a user is who they say they are (e.g. logging in with a username and password).

To learn more about the different types of user permissions built into this SaaS template, including Stripe subscription tiers and statuses, check out the User Overview Reference.

Also, check out our blog post to learn more about authorization (access control) in web apps.

Client-side Authorization Copy Section

Open Saas starts with all users having access to the landing page (/), but only authenticated users having access to the rest of the app (e.g. to the /demo-app, or to the /account).

To control which pages require users to be authenticated to access them, you can set the authRequired property of the corresponding page definition in your main.wasp file:

route AccountRoute { path: "/account", to: AccountPage }
page AccountPage {
  authRequired: true,
  component: import Account from "@src/user/AccountPage"
}

This will automatically redirect users to the login page if they are not logged in while trying to access that page.

:::caution[Client-side authorization is just for the looks]
Users can manipulate the client code as they wish, meaning that client-side authorization (access control) serves the purpose of ergonomics/user experience, not the purpose of restricting access to sensitive data.

This means that authorization in the client code is a nice-to-have: it is here to make sure users don't get lost in the part of the app they can't work with because data is missing due to them not having access, not to actually restrict them from doing something.

Actually ensuring they don't have access to the data, that is on the server to ensure, via server-side logic that you will implement for authorization.
:::

If you want more fine-grained control over what users can access, there are two Wasp-specific options:

1. When you define the authRequired: true property on the page definition, Wasp automatically passes the User object to the page component. Here you can check for certain user properties before authorizing access:

import { type User } from "wasp/entities";

export function ExamplePage({ user }: { user: User }) {
  if (user.subscriptionStatus === 'past_due') {
    return (<span>Your subscription is past due. Please update your payment information.</span>)
  }
  if (user.subscriptionStatus === 'cancel_at_period_end') {
    return (<span>Your susbscription will end on 01.01.2024</span>)
  }
  if (user.subscriptionStatus === 'active') {
    return (<span>Thanks so much for your support!</span>)
  }
};

2. Or you can take advantage of the useAuth hook and check for certain user properties before authorizing access to certain pages or components:

import { useAuth } from "wasp/client/auth";

export function ExampleComponent() {
  const { data: user } = useAuth();

  return (
    <h1> Hi {user.email || 'there'} 👋 </h1>
  )
}

Server-side Authorization Copy Section

Authorization on the server-side is the core of your access control logic, and determines what users actually can or can't do (unlike client-side authorization logic which is there merely for UX).

You can authorize access to server-side operations by adding a check for a logged-in user on the context.user object which is passed to all operations in Wasp:

export const someServerAction: SomeServerAction<...> = async (args, context) => {
  if (!context.user) {
    throw new HttpError(401); // Throw an error if user is not logged in.
  }

  if (context.user.subscriptionStatus === 'past_due') {
    throw new HttpError(403, 'Your subscription is past due. Please update your payment information.');
  }
  //...
}

Opensaas Sh Blog Src Content Docs 0.23 Guides Cookie Consent (`opensaas-sh/blog/src/content/docs/0.23/guides/cookie-consent.mdx`) Copy Section

title: Cookie Consent Modal
banner:
content: >
Have an Open SaaS app in production? We'll send you some
swag! 👕

slug: 0.23/guides/cookie-consent Copy Chapter

import cookieBanner from '@assets/cookie-consent/cookiebanner.png';
import preferences from '@assets/cookie-consent/preferences.png';
import { Image } from 'astro:assets';

Cookie consent banners are annoying, we know. But they are legally required in many countries, so we have to deal with them.

This guide will help you dynamically add or remove cookies from your app via the cookie consent modal that comes with this template.

This is needed for non-essential cookies that are not necessary for the basic functionality of your app, such as analytics cookies or marketing cookies.

The cookie consent modal can be found at app/src/client/components/cookie-consent/ and contains two main files:

1. Banner.tsx - the component that displays the banner at the bottom of the page.
2. Config.ts - the configuration file that contains the cookies/scripts that will be dynamically added.

The Banner.tsx component is imported in app/src/client/App.tsx and is rendered at the bottom of the page, while all the changes to the banner itself are done within the Config.ts file, which we explain below.

Configuration Copy Chapter

We decided to use the vanilla-cookieconsent library to handle the cookie consent. We've set it up to give you some basic functionality, using mostly the default settings. For a full list of options, you can check the official documentation.

Below, we will guide you through the necessary steps to get the cookie consent modal set up for your app.

Google Analytics Copy Section

What's impotant to note for this template is that we are simply using the onAccept callbacks to dynamically add or remove our Google Analytics cookies from the page. In order for it to work correctly with your app, you need to add your Google Analytics ID to your .env.client file.

REACT_APP_GOOGLE_ANALYTICS_ID=G-1234567890

And that's it! The cookie consent modal will now dynamically add or remove the Google Analytics cookies based on the user's choice.

To check if it's working correctly, you can open the browser's developer tools and check the cookies tab. You should see the following cookies being added or removed based on the user's choice:

_ga
_ga... # Google Analytics cookies.
cc_cookie # Cookie Consent cookie. The name of this cookie can be changed in the config file.

Plausible Analytics Copy Section

If you decide to go with Plausible Analytics, you DO NOT need to ask users for their consent to use cookies because Plausible, as a privacy-first analytics provider, does not use cookies. Instead, It collects website usage data anonymously and in aggregate form only, without any personally identifiable information

By avoiding cookies, Plausible Analytics avoids the need for cookie consent banners.

Your Terms / Privacy Policy Copy Section

You should also add a link to your terms and privacy policy within consentModal section of config.language:

language: {
      default: 'en',
      translations: {
        en: {
          consentModal: {
            title: 'We use cookies',
            // ...
            // TODO: Add your own privacy policy and terms and conditions links below.
            footer: `
            <a href="<your-url-here>" target="_blank">Privacy Policy</a>
            <a href="<your-url-here>" target="_blank">Terms and Conditions</a>
                    `,
          },
        },
      },
    }

Allowing Users to Control Certain Cookies (OPTIONAL) Copy Section

If you've added more than just Google Analytics cookies to your app, you can allow users to control which cookies they want to accept or reject. For example, if you've added marketing cookies, you can add a button to the modal that allows users to reject them, while accepting analytics cookies.

To do that, you can change the preferencesModal.sections property in config.language. Any section that you add to preferencesModal.sections must match a linkedCategory in the config.categories property. Make sure you also add a showPreferencesBtn property to consentModal (highlighted below).

Below is an example of what your config might look like if you want to give users the option to control over multiple cookie preferences:

/* Detailed source-code truncated for AI context efficiency. */

For more information on how to do that, check the official documentation.

Opensaas Sh Blog Src Content Docs 0.23 Guides Deploying (`opensaas-sh/blog/src/content/docs/0.23/guides/deploying.mdx`) Copy Section

title: Deploying
banner:
content: >
Have an Open SaaS app in production? We'll send you some
swag! 👕

slug: 0.23/guides/deploying Copy Chapter

import stripeListenEvents from '@assets/stripe/listen-to-stripe-events.png';
import npmVersion from '@assets/stripe/npm-version.png';
import stripeSigningSecret from '@assets/stripe/stripe-webhook-signing-secret.png';
import { Image } from 'astro:assets';

Because this SaaS app is a React/NodeJS/Postgres app built on top of Wasp, Open SaaS can take advantage of Wasp's easy, one-command deploy or manual deploy to any provider of your choice.

The simplest and quickest option is to take advantage of Wasp's one-command deploy to Fly.io or Railway.

Or if you prefer to deploy to a different provider, or your frontend and backend separately, you can follow the Deploying Manually section below.

Steps for Deploying Copy Chapter

These are the steps necessary for you to deploy your app. We recommend you follow these steps in order.

• [ ] Get your production API keys and environment variables.
• [ ] Set your production environment variables on your deployed apps.
• [ ] Add the correct redirect URL's to your social auth credentials.
• [ ] Set your production settings for your payment provider.
• [ ] Customize SEO and discoverability (meta tags, JSON-LD, llms.txt).
• [ ] Deploy your App through Wasp Deploy commands or manually to any provider.
• [ ] (Optional) Deploy your blog.

Each of these steps is covered in more detail below.

Prerequisites Copy Chapter

AWS S3 CORS configuration Copy Section

If you're storing files in AWS S3, ensure you've listed your production domain
in the bucket's CORS configuration under AllowedOrigins. Check the File
uploading guide for details.

Env Vars Copy Section

Make sure you've got all your API keys and environment variables set up before you deploy.

Payment Processor Vars

In the Payments Processor integration guide, you set up your API keys using test keys and test product ids. You'll need to get the live/production versions of those keys. To get these, repeat the instructions in the Integration Guide without being in test mode. Add the new keys to your deployed environment secrets.

Other Vars

Many of your other environment variables will probably be the same as in development, but you should double-check that they are set correctly for production.

Here are a list of all of them (some of which you may not be using, e.g. Analytics, Social Auth) in case you need to check:

General Vars

• [ ] DATABASE_URL
• [ ] JWT_SECRET
• [ ] WASP_WEB_CLIENT_URL
• [ ] WASP_SERVER_URL

Open AI API Key

• [ ] OPENAI_API_KEY

Sendgrid API Key

• [ ] SENDGRID_API_KEY

Social Auth Vars

• [ ] GOOGLE_CLIENT_ID
• [ ] GOOGLE_CLIENT_SECRET
• [ ] GITHUB_CLIENT_ID
• [ ] GITHUB_CLIENT_SECRET

Analytics Vars

• [ ] REACT_APP_PLAUSIBLE_ANALYTICS_ID (for client-side)
• [ ] PLAUSIBLE_API_KEY
• [ ] PLAUSIBLE_SITE_ID
• [ ] PLAUSIBLE_BASE_URL
• [ ] REACT_APP_GOOGLE_ANALYTICS_ID (for client-side)
• [ ] GOOGLE_ANALYTICS_CLIENT_EMAIL
• [ ] GOOGLE_ANALYTICS_PROPERTY_ID
• [ ] GOOGLE_ANALYTICS_PRIVATE_KEY
  (Make sure you convert the private key within the JSON file to base64 first with echo -n "PRIVATE_KEY" | base64. See the Analytics docs for more info)

AWS S3 Vars

• [ ] AWS_S3_IAM_ACCESS_KEY
• [ ] AWS_S3_IAM_SECRET_KEY
• [ ] AWS_S3_FILES_BUCKET
• [ ] AWS_S3_REGION

:::tip[Deployed? Get some swag! 👕]
Do you have an Open SaaS app running in production? If yes, we'd love to send some swag your way! All you need to do is fill out this form and we'll make it happen.
:::

Adding Server Redirect URL's to Social Auth Copy Chapter

After deploying your server, you need to add the correct redirect URIs to the credential settings. For this, refer to the guides from the Wasp Docs.

Payment Providers Production Settings Copy Chapter

Stripe Copy Section

Now you need to set up your stripe webhook for production use. Below are some important steps and considerations you should take as you prepare to deploy your app to production.

Stripe API Versions

When you create your Stripe account, Stripe will automatically assign you to their latest API version at that time. This API version is important because it determines the structure of the responses Stripe sends to your webhook, as well as the structure it expects of the requests you make toward the Stripe API.

Because this template was built with a specific version of the Stripe API in mind, it could be that your Stripe account is set to a different API version.

:::note

const STRIPE_API_VERSION = "2025-04-30.basil"; // or e.g. 2023-08-16 if using older format

export const stripeClient = new Stripe(env.STRIPE_API_KEY, {
  apiVersion: STRIPE_API_VERSION,
});

When you specify a specific API version in your Stripe client, the requests you send to Stripe from your server, along with their responses, will match that API version. On the other hand, Stripe will send all other events to your webhook that didn't originate as a request sent from your server, like those made after a user completes a payment on checkout, using the default API version of the API.

This is why it's important to make sure your Stripe client version also matches the API version in your Stripe account, and to thoroughly test any changes you make to your Stripe client before deploying to production.
:::

To make sure your app is consistent with your Stripe account, here are some steps you can follow:

1. You can find your default API version in the Stripe dashboard under the Developers section.
2. Check that the API version in your /src/payment/stripe/stripeClient.ts file matches the default API version in your dashboard:
   ts title="stripeclient.ts" {1} Copy

   const STRIPE_API_VERSION = "2025-04-30.basil"; // or e.g. 2023-08-16 if using older format
   
   export const stripeClient = new Stripe(env.STRIPE_API_KEY, {
     apiVersion: STRIPE_API_VERSION,
   });

3. If they don't match, you can upgrade/downgrade your Stripe NPM package in package.json to match the API version in your dashboard:

• If your default version on the Stripe dashboard is also the latest version of the API, you can simply upgrade your Stripe NPM package to the latest version.
• If your default version on the Stripe dashboard is not the latest version, and you don't want to upgrade to the latest version, because e.g. you have other projects that depend on the current version, you can find and install the Stripe NPM package version that matches your default API version by following these steps:

  • Find and note the date of your default API version in the developer dashboard.

  • Go to the Stripe NPM package page and hover over Published date column until you find the package release that matches your version. For example, here we find the NPM version 13.x.x matches the API version of 2023-08-16.

  • Install the correct version of the Stripe NPM package by running:

    sh Copy

    npm install [email protected] # e.g. npm install [email protected]

4. Test your app thoroughly to make sure that the changes you made to your Stripe client are working as expected before deploying to production.

Creating Your Production Webhook

1. Go to https://dashboard.stripe.com/webhooks

2. Click on + add endpoint

3. Enter your endpoint url, which will be the url of your deployed server + /payments-webhook, e.g. https://open-saas-wasp-sh-server.fly.dev/payments-webhook

4. Select the events you want to listen to. These should be the same events you're consuming in your webhook which are handled in src/payment/stripe/webhook.ts:

5. After that, go to the webhook you just created and reveal the new signing secret.

6. Add this secret to your deployed server's STRIPE_WEBHOOK_SECRET environment variable. If you've deployed to Fly.io, you can do that easily with the following command:

   sh Copy

   wasp deploy fly cmd --context server secrets set STRIPE_WEBHOOK_SECRET=whsec_...

Lemon Squeezy Copy Section

Creating Your Production Webhook

To set up your Lemon Squeezy webhook, you'll need the URL of you newly deployed server + /payments-webhook, e.g. https://open-saas-wasp-sh-server.fly.dev/payments-webhook.

With the webhook url ready, go to your Lemon Squeezy Webhooks Dashboard:

1. Click the + button.
2. Add the webhook forwarding url to the Callback URL section.
3. Give your webhook a signing secret (a long, random string).
4. Add this signing secret to your server's production environment variables under LEMONSQUEEZY_WEBHOOK_SECRET.
5. Make sure to select at least the following updates to be sent:
   • order_created
   • subscription_created
   • subscription_updated
   • subscription_cancelled
6. Click save.