+ Docs
+
+
+
+
\ No newline at end of file
diff --git a/opensaas-sh/blog/src/components/MyThemeSelect.astro b/opensaas-sh/blog/src/components/MyThemeSelect.astro
new file mode 100644
index 000000000..1110ec503
--- /dev/null
+++ b/opensaas-sh/blog/src/components/MyThemeSelect.astro
@@ -0,0 +1,28 @@
+---
+import StarlightThemeSelect from '@astrojs/starlight/components/ThemeSelect.astro'
+import type { Props } from '@astrojs/starlight/props'
+---
+
+{title}
+{subtitle &&{subtitle}
} +{imageExists &&
+
}
+
+
\ No newline at end of file
diff --git a/opensaas-sh/blog/src/components/Tweet.astro b/opensaas-sh/blog/src/components/Tweet.astro
new file mode 100644
index 000000000..0229f6a0e
--- /dev/null
+++ b/opensaas-sh/blog/src/components/Tweet.astro
@@ -0,0 +1,48 @@
+---
+interface Props {
+ id: string;
+}
+
+const { id } = Astro.props;
+---
+
+
+
+
+
+
\ No newline at end of file
diff --git a/opensaas-sh/blog/src/components/VideoPlayer.astro b/opensaas-sh/blog/src/components/VideoPlayer.astro
new file mode 100644
index 000000000..8b4050127
--- /dev/null
+++ b/opensaas-sh/blog/src/components/VideoPlayer.astro
@@ -0,0 +1,56 @@
+---
+interface Props {
+ src: string;
+ lgWidth?: string;
+ smWidth?: string;
+}
+
+const { src, lgWidth = '55%', smWidth = '100%' } = Astro.props;
+
+// Function to check if the URL is a YouTube URL and, if so, extract the video ID
+function getYouTubeId(url: string): string | null {
+ const regExp = /^.*(youtu.be\/|v\/|u\/\w\/|embed\/|watch\?v=|&v=)([^#&?]*).*/;
+ const match = url.match(regExp);
+ return match && match[2].length === 11 ? match[2] : null; // Note: all YouTube video IDs are 11 characters long.
+}
+
+const youTubeId = getYouTubeId(src);
+const isYouTube = !!youTubeId;
+---
+
+{isYouTube ? (
+
+) : (
+
+)}
+
+
\ No newline at end of file
diff --git a/opensaas-sh/blog/src/components/imagePaths.ts b/opensaas-sh/blog/src/components/imagePaths.ts
new file mode 100644
index 000000000..73ec00871
--- /dev/null
+++ b/opensaas-sh/blog/src/components/imagePaths.ts
@@ -0,0 +1,16 @@
+import path from 'path';
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+export const BANNER_PATH = '/banner-images';
+
+export const DEFAULT_BANNER_IMAGE = 'opensaas.webp';
+
+export const getBannerImageFilename = ({ path }: { path: string }) =>
+ path.replace(/.*\//, '').replace(/\.\w+$/, '.webp');
+
+export const checkBannerImageExists = ({ bannerImageFileName }: { bannerImageFileName: string }) => {
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
+ const imagePath = path.join(__dirname, `../../public/${BANNER_PATH}`, bannerImageFileName);
+ return existsSync(imagePath);
+};
diff --git a/opensaas-sh/blog/src/content/config.ts b/opensaas-sh/blog/src/content/config.ts
new file mode 100644
index 000000000..019002ea8
--- /dev/null
+++ b/opensaas-sh/blog/src/content/config.ts
@@ -0,0 +1,20 @@
+import { defineCollection } from 'astro:content';
+import { i18nSchema, docsSchema } from '@astrojs/starlight/schema';
+import { blogSchema } from 'starlight-blog/schema';
+import { z } from 'astro:content';
+
+export const collections = {
+ docs: defineCollection({
+ schema: docsSchema({
+ extend: (context) => {
+ const blogSchemaResult = blogSchema(context);
+ return z.object({
+ ...blogSchemaResult.shape,
+ subtitle: z.string().optional(),
+ hideBannerImage: z.boolean().optional(),
+ });
+ },
+ }),
+ }),
+ i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
+};
\ No newline at end of file
diff --git a/opensaas-sh/blog/src/content/docs/blog/2023-11-21-coverlettergpt.mdx b/opensaas-sh/blog/src/content/docs/blog/2023-11-21-coverlettergpt.mdx
new file mode 100644
index 000000000..1d6694cbf
--- /dev/null
+++ b/opensaas-sh/blog/src/content/docs/blog/2023-11-21-coverlettergpt.mdx
@@ -0,0 +1,160 @@
+---
+title: How I Built & Grew CoverLetterGPT to 5,000 Users and $200 MRR
+date: 2023-11-21
+tags: ["indiehacker", "saas", "sideproject"]
+authors: vince
+---
+import { Image } from 'astro:assets';
+
+## Hey, Iβm Vinceβ¦
+
+
+ βοΈ Star Open SaaS repo and support tools that help you build fast!
+
+
+### Out-of-the-box Stripe integration
+
+Another significant advantage for Peter was how Open SaaS handled third-party integrations. Setting up services like [**Stripe for payments**](https://docs.opensaas.sh/guides/payments-integration/) often requires a lot of effort, but Wasp's OpenSaaS streamlined the process - you just need to add your API key and you're good to go.
+
+> *"Payments are usually a huge headache, but Open SaaS made it so smooth. I didn't have to spend weeks integrating Stripeβit just worked. That gave me more time to focus on TurboReel's core functionality.*"
+
+
+### The power of open source
+
+Both TurboReel and Wasp share a commitment to open source.
+
+> *"The video generation space is complex. There aren't many established solutions for what I'm trying to do. [By making TurboReel open source](https://github.com/TurboReel), I'm inviting smart people to collaborate and help push the project forward."*
+
+
+## Getting first users
+
+
+ 
+
+
+What Ricardo loves most:
+
+- **Pre-built Features**: Open SaaS relies on Wasp - a full stack framework for React, Node.js and Prisma. The way Wasp handles routes and authentication was a game-changer.
+
+> *"Just putting routes in `main.wasp` makes everything super simple. Auth works seamlessly, too."*
+
+- **Focus on Building**: By handling repetitive setup tasks like setting up payment integrations or making admin dashboards, Open SaaS allowed Ricardo to focus on core features.
+- **Adaptability**: regardless of the idea he had - a full-fledged SaaS, or a Google add-on which needed a robust-backend and a dashboard, he was able to build the app with Open SaaS boilerplate starter.
+
+> *"I didn't feel limited by the boilerplateβit's flexible and gets out of the way."*
+
+## Ricardo's Projects Built with Wasp
+
+Ricardo started a few projects with Wasp, while working on the third one he started before discovering Open SaaS.
+
+### **Article Generator**
+
+- Built in less than 7 days.
+- 40+ paying customers.
+
+[This tool](https://article-generation.com/) simplifies content creation for businesses by generating SEO-friendly blog posts with AI. Article Generator is competing in a crowded market of AI writing tools, where each tool claims that it's the best one on the market.
+
+
+
+
+
+
+In this case, Open SaaS handles backend tasks like subscription checks and authentication. Because of that, this is a lightweight app that solves a niche problem effectively, and doesn't require a lot of maintenance.
+
+The first users were people he knew personally, and he did a bit of promotion on targeted groups on Slack and Discord. Since it's a Google Marketplace app, anyone looking for Meeting Reminder add-on will have a chance to see it.
+
+
+
+
+He also relies on SEO, and guess what, he pushed a couple of blog posts with his first SaaS, AI Article Generator. As he said before, you should make tools that scratch your itch first. π
+
+### Tips for Builders Launching Products
+
+1. **Validate Before You Build**
+
+> *"Start by searching Reddit or similar platforms to find out if people are already solving the problem. If they are, ask yourself: can I do it better or faster?"*
+
+
+ 
+
+
+2. **Diversify Launch Strategies**
+
+- Avoid relying solely on Product Hunt
+
+> *"It's not as effective as it used to be."*
+
+- Explore short-form content like TikTok for quick validation. You can create a company account and post videos that showcase the problem and the solution.
+
+
++ +> *"Their algorithm is great for targeting the right audience."* + +- Use targeted Reddit ads to reach niche communities. + +3. **Start small** + +> *"If you're entering a competitive space, start small. Validate your product's unique edge by solving specific pain points and adjust based on user feedback."* + +4. **Iterate Quickly** + +> *"Launch fast, gather feedback, and refine your product. You don't need to build the perfect app on day oneβget it out there, see how people use it, and adjust."* + + +### **Ready to Build Your SaaS?** + +Explore the [Open SaaS boilerplate](https://opensaas.sh/) to see how you can kickstart your SaaS today. + +@meetingreminders BOOOM!! no more waiting in meetings - it's called Meeting Reminders #workmeeting #corporate #workfromhome #googlemeet
β¬ original sound - Meeting Reminders
Hi {user.email || 'there'} π
+ ) +} +``` + +### Server-side Authorization + +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: + +```tsx title="src/server/actions.ts" +export const updateCurrentUser: UpdateCurrentUser<...> = 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.'); + } + //... +} +``` + + diff --git a/opensaas-sh/blog/src/content/docs/guides/cookie-consent.mdx b/opensaas-sh/blog/src/content/docs/guides/cookie-consent.mdx new file mode 100644 index 000000000..ff68aa0b8 --- /dev/null +++ b/opensaas-sh/blog/src/content/docs/guides/cookie-consent.mdx @@ -0,0 +1,161 @@ +--- +title: Cookie Consent Modal +banner: + content: | + Have an Open SaaS app in production? We'll send you some swag! π +--- +import { Image } from 'astro:assets'; +import cookieBanner from '@assets/cookie-consent/cookiebanner.png'; +import preferences from '@assets/cookie-consent/preferences.png'; + +- `account.updated` +
- `checkout.session.completed` +
- `customer.subscription.deleted` +
- `customer.subscription.updated` +
- `invoice.paid` +
If you've deployed to Fly.io, you can do that easily with the following command: +```sh +wasp deploy fly cmd --context server secrets set STRIPE_WEBHOOK_SECRET=whsec_... +``` + +### Setting up your Production Lemon Squeezy 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](https://app.lemonsqueezy.com/settings/webhooks): +- click the `+` button. +- add the webhook forwarding url to the `Callback URL` section. +- give your webhook a signing secret (a long, random string). +- add this signing secret to your server's production environment variables under `LEMONSQUEEZY_WEBHOOK_SECRET=` +- make sure to select at least the following updates to be sent: + - order_created + - subscription_created + - subscription_updated + - subscription_cancelled +- click `save` + + +## Deploying your Blog + +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](https://docs.netlify.com/cli/get-started/) 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: + +```sh +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: + +```sh +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: + +```sh +netlify deploy --prod +``` + diff --git a/opensaas-sh/blog/src/content/docs/guides/email-sending.mdx b/opensaas-sh/blog/src/content/docs/guides/email-sending.mdx new file mode 100644 index 000000000..e10c60e41 --- /dev/null +++ b/opensaas-sh/blog/src/content/docs/guides/email-sending.mdx @@ -0,0 +1,107 @@ +--- +title: Email Sending +banner: + content: | + Have an Open SaaS app in production? We'll send you some swag! π +--- +import { Tabs, TabItem } 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 + +### The `Dummy` Email Provider (for Local Dev Only) +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. +```tsx title="main.wasp" +app SaaSTemplate { + // ... + emailSender: { + provider: Dummy, + defaultFrom: { + name: "Open SaaS App", + email: "me@example.com" + }, + }, +``` + +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) +To change your email provider to a production-ready one, such as SendGrid, you'll want to configure your `emailSender` like so: + +```tsx title="main.wasp" +app SaaSTemplate { + // ... + 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: "me@example.com" + }, + }, +``` + +This means that you can send emails from your app using the `send` function from the `email` modul provided by Wasp: + +```tsx title="src/server/webhooks.ts" +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 + +To set up your email sender, you first need an account with one of the supported email providers. + +
+
+:::
+
+### Linux and macOS
+
+Open your terminal and run:
+
+```shell
+curl -sSL https://get.wasp-lang.dev/installer.sh | sh
+```
+
+:::caution[Bad CPU type in executable]
++ Need help with nvm? +
+
+ Install nvm via your OS package manager (`apt`, `pacman`, `homebrew`, ...) or via the [nvm](https://github.com/nvm-sh/nvm#install--update-script) install script.
+
+ Then, install a version of Node.js that you need:
+
+ ```shell
+ nvm install 20
+ ```
+
+ Finally, whenever you need to ensure a specific version of Node.js is used, run:
+
+ ```shell
+ nvm use 20
+ ```
+
+ to set the Node.js version for the current shell session.
+
+ You can run
+
+ ```shell
+ node -v
+ ```
+
+ to check the version of Node.js currently being used in this shell session.
+
+ Check NVM repo for more details: [https://github.com/nvm-sh/nvm](https://github.com/nvm-sh/nvm).
+
+
+
+:::
+
+### Windows
+
+In order to use Wasp on Windows, you need to install WSL2 (Windows Subsystem for Linux) and a Linux distribution of your choice. We recommend using Ubuntu.
+
+**You can refer to this [article](https://wasp.sh/blog/2023/11/21/guide-windows-development-wasp-wsl) for a step by step guide to using Wasp in the WSL environment.** If you need further help, reach out to us on [Discord](https://discord.gg/rzdnErX).
+
+:::caution[WSL2 Docker post installation steps]
+
++ Are you getting this error on a Mac (Apple Silicon)? +
+Given that the wasp binary is built for x86 and not for arm64 (Apple Silicon), you'll need to install Rosetta on your Mac if you are using a Mac with Mx (M1, M2, ...). Rosetta is a translation process that enables users to run applications designed for x86 on arm64 (Apple Silicon). To install Rosetta, run the following command in your terminal + +```bash +softwareupdate --install-rosetta +``` +Once Rosetta is installed, you should be able to run Wasp without any issues. + +
+
+:::
+
+
+Once in WSL2, run the following command in your **WSL2 environment**:
+```sh
+curl -sSL https://get.wasp-lang.dev/installer.sh | sh
+```
+
+:::caution[WSL2 and file system issues]
++ Complete those steps to ensure that PostgreSQL and Docker work correctly with Wasp in WSL2. +
+It is recommended to complete those post-install steps in WSL, based on the official Docker guide. These work if you are experiencing an error similar to this one. + +First, run + +```bash +sudo groupadd docker +``` + +command to create the `docker` group in case it doesn't exist. If it exists, don't worry, just continue with next steps. After that, add your current user to docker group by running + +```bash +sudo usermod -aG docker $USER +``` + +where $USER is your username. After that, log out and log back in to apply the changes. Finally, run + +```bash +su -s $USER +``` + +
+
+:::
+
+### Finalize Installation
+
+Run the following command to verify that Wasp was installed correctly:
+
+```shell
+wasp version
+```
+
+Also be sure to install the Wasp VSCode extension to get the best DX, e.g. syntax highlighting, code scaffolding, autocomplete, etc.
+
+:::tip[Installing the Wasp VSCode Extension]
+You can install the Wasp VSCode extension by searching for "Wasp" in the Extensions tab in VSCode, or by visiting the π [Wasp VSCode Extension](https://marketplace.visualstudio.com/items?itemName=wasp-lang.wasp) π§βπ» homepage
+:::
+
+## Setting up your SaaS app
+
+### Cloning the OpenSaaS template
+
+From the directory where you'd like to create your new project run:
+```sh
+wasp new
+```
+
+Then select option `[3] saas` from the list of templates after entering the name of your project.
+
+This will clone a **clean copy of the Open SaaS template** into a new directory! π
+
+### Start your DB
+
+Before you start your app, you need to have a Postgres Database connected and running. With Wasp, that's super easy!
+
+First, make sure you have **Docker installed and running**. If not, download and install it [here](https://www.docker.com/products/docker-desktop/)
+
+With Docker running, open a new terminal window/tab and position yourself in the `app` directory:
+
+```sh
+cd app
+```
+
+Then run:
+
+```sh
+wasp start db
+```
+
+This will start and connect your app to a Postgres database for you. No need to do anything else! π€― Just make sure to leave this terminal window open in the background while developing. Once you terminate the process, your DB will no longer be available to your app.
+
+Now let's create our very first database migration, to ensure the database has a correct schema. Open a new terminal tab/window and run the following command:
+
+```sh
+wasp db migrate-dev
+```
+
+This might take a bit since this is the first time you are running it and it needs to install all the
+dependencies for your Wasp project.
+
+In the future, you will also want to run `wasp db migrate-dev` whenever you make changes to your Prisma schema (Entities),
+to apply those schema changes to the database.
+
+Additionally, if you want to see or manage your DB via Prisma's DB Studio GUI, run:
+
+```sh
+wasp db studio
+```
+
+### Start your app
+
+At this point, you should be positioned in the `app/` directory and have the database running in another terminal session.
+
+Next, copy the `.env.server.example` file to `.env.server`.
+
+```sh
+cp .env.server.example .env.server
+```
+
+`.env.server` is where API keys for services like payments, email sender, and similar go, and this is where you will want to put them in later.
+For now, you can leave it as it is (dummy API keys), this will be enough to run the app.
+
+Then run:
+
+```sh
+wasp start
+```
+
+This will install all the dependencies and start the app (client and server) for you :)!
+
+If the app doesn't open automatically in your browser, you can open it manually by visiting `http://localhost:3000` in your browser.
+
+At this point, you should have:
+ - your database running in one terminal session, likely on port `5432`.
+ - your app running in another terminal session, the client likely on port `3000`, and the server likely on port `3001`.
+
+#### Run Blog and Docs
+
+This SaaS app comes with a docs and blog section built with the [Starlight template on top of the Astro](https://starlight.astro.build) framework. You can use this as a starting point for your own blog and documentation, if necessary.
+
+If you do not need this, you can simply delete the `blog` folder from the root of the project.
+
+If you want to run the Starlight docs and blog, first navigate to the `blog` folder:
+
+```sh
+cd ../blog
+```
+
+Then run:
+
+```sh
+npm install
+```
+
+Then start the development server:
+
+```sh
+npm run dev
+```
+
+Check the instructions in the terminal for the link to open the blog, it will typically be `https://localhost:4321/`.
+
+## What's next?
+
+Awesome! We have our new app ready and we know how to run both it and the blog/docs! Now, in the next section, we'll give you a quick "guided tour" of the different parts of the app we created and understand how it works.
+
+:::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](https://github.com/wasp-lang/wasp)
+:::
diff --git a/opensaas-sh/blog/src/content/docs/start/guided-tour.md b/opensaas-sh/blog/src/content/docs/start/guided-tour.md
new file mode 100644
index 000000000..b0bea0bd1
--- /dev/null
+++ b/opensaas-sh/blog/src/content/docs/start/guided-tour.md
@@ -0,0 +1,350 @@
+---
+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**!
+```sh title="server logs"
+[ Server ] βββββββββββββββββββββββββ
+[ Server ] β Dummy email sender βοΈ β
+[ Server ] βββββββββββββββββββββββββ
+[ Server ] From: Open SaaS App + Are you getting file system issues using WSL2? +
+If you are using WSL2, make sure that your Wasp project is not on the Windows file system, but instead on the Linux file system. Otherwise, Wasp won't be able to detect file changes, due to this issue in WSL2. +Click the link below to verify your email
+[ Server ] Verify email +[ 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](https://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 +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: +```sh +. +βββ app +βββ blog +βββ e2e-tests +``` + +`app` contains the Wasp project files, which is your full-stack React + NodeJS + Prisma app along with a Wasp config file, `main.wasp`, which will be explained in more detail below. + +`blog` contains the [Astro Starlight template](https://starlight.astro.build/) 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 + +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: + +:::caution[v0.13 and below] +If you are using an older version of the OpenSaaS template with Wasp `v0.13.x` or below, you may see a slightly different file structure. But don't worry, the vast majority of the code and features are the same! π +::: + +```sh +. +βββ main.wasp # Wasp Config file. You define your app structure 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 +βΒ Β βββ messages # Logic for app user messages. +βΒ Β βββ newsletter/ # Logic for scheduled recurring newsletter sending. +βΒ Β βββ 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. +βββ tailwind.config.js # TailwindCSS configuration. +βββ package.json +βββ package-lock.json +βββ .wasproot +``` + +### The Wasp Config file + +This template at its core is a Wasp project, where [Wasp](https://wasp.sh) 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](https://wasp.sh/docs) is its use of a config file (`main.wasp`) and compiler which takes your code and outputs the client app, server app and deployment code for you. + +In this template, we've already defined a number of things in the `main.wasp` config file, including: + +- [Auth](https://wasp.sh/docs/auth/overview) +- [Routes and Pages](https://wasp.sh/docs/tutorial/pages) +- [Prisma Database Models](https://wasp.sh/docs/data-model/entities) +- [Operations (data read and write functions)](https://wasp.sh/docs/data-model/operations/overview) +- [Background Jobs](https://wasp.sh/docs/advanced/jobs) +- [Email Sending](https://wasp.sh/docs/advanced/email) + +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](https://wasp.sh/docs) which takes ~20 minutes. +::: + +### Client + +The `src/client` folder contains any additional client-side code that doesn't belong to a feature: + +```sh +. +βββ client + βββ components # Your shared React components. + βββ fonts # Extra fonts + βββ hooks # Your shared React hooks. + βββ icons # Your shared SVG icons. + βββ 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. + βββ cn.ts # Helper function for dynamic and conditional Tailwind CSS classes. + βββ Main.css + +``` + +### Server + +The `src/server` folder contains any additional server-side code that does not belong to a specific feature: + +```sh +βββ server + βββ scripts # Scripts to run via Wasp, e.g. database seeding. + βββ utils.ts +``` + +## Main Features + +### Auth + +This template comes with a fully functional auth flow out of the box. It takes advantages of Wasp's built-in [Auth features](https://wasp.sh/docs/auth/overview), which do the dirty work of rolling your own full-stack auth for you! + +```js title="main.wasp" + auth: { + userEntity: User, + methods: { + email: { + //... + }, + google: {}, + github: {}, + discord: {} + }, + onAuthFailedRedirectTo: "/", + }, +``` + +By defining the auth structure in your `main.wasp` file, Wasp manages all the necessary code for you, including: +- Email verified login with reset password +- 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 reset password +- Auth hooks for fetching user data + + + +We've set the template up with Wasp's `email`, `google`, 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 at `app.emailSender` in the `main.wasp` 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. + +```tsx title="main.wasp" + emailSender: { + provider: Dummy, // logs all email verification links/tokens to the server's console + defaultFrom: { + name: "Open SaaS App", + email: "me@example.com" + }, + }, +``` +::: + +We will explain more about these auth methods, and how to properly integrate them into your app, in the [Authentication Guide](/guides/authentication/). + +### Subscription Payments with Stripe or Lemon Squeezy + +No SaaS is complete without payments, specifically subscription payments. That's why this template comes with a fully functional Stripe or Lemon Squeezy 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 Checkout page where they enter their payment info +3. the user is redirected back to the app and the Checkout session is completed +4. Stripe / Lemon Squeezy sends a webhook event to the 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 or Lemon Squeezy) and its related functions can be found at `src/payment/paymentProcessor.ts`. The `Payment Processor` object holds the logic for creating checkout sessions, webhooks, etc. + +The logic for creating the Checkout session is defined in the `src/payment/operation.ts` file. [Actions](https://wasp.sh/docs/data-model/operations/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 `main.wasp` file, you can easily call them on the client-side: + +a) define the action in the `main.wasp` file +```js title="main.wasp" +action generateCheckoutSession { + fn: import { generateCheckoutSession } from "@src/payment/operations", + entities: [User] +} +``` + +b) implement the action in the `src/payment/operations` file +```js title="src/server/actions.ts" +export const generateCheckoutSession = async (paymentPlanId, context) => { + //... + } +``` + +c) call the action on the client-side +```js title="src/client/app/SubscriptionPage.tsx" +import { generateCheckoutSession } from "wasp/client/operations"; + +const handleBuyClick = async (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 `main.wasp` file as an API endpoint in order to expose it externally to Stripe + +```js title="main.wasp" +api paymentsWebhook { + fn: import { paymentsWebhook } from "@src/payment/webhook", + httpRoute: (POST, "/payments-webhook") + entities: [User], +} +``` + +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. + +To learn more about configuring the app to handle your products and payments, check out the [Payments Integration guide](/guides/payments-integration/). + +:::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](https://github.com/wasp-lang/wasp) +::: + + +### Analytics and Admin Dashboard + +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](https://wasp.sh/docs/advanced/jobs) 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! + +```js title="main.wasp" +job dailyStatsJob { + executor: PgBoss, + perform: { + fn: import { calculateDailyStats } from "@src/analytics/stats" + }, + schedule: { + cron: "0 * * * *" // runs every hour + }, + entities: [User, DailyStats, Logs, PageViewSource] +} +``` + +For more info on integrating Plausible or Google Analytics, check out the [Analytics guide](/guides/analytics/). + +## App Customization Walkthrough + +### General Considerations + +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, GitHub) +- Stripe or Lemon Squeezy +- OpenAI (Chat GPT 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](https://wasp.sh/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 +#### `main.wasp` Config File +- [ ] Change the app name and title: + ```ts title="main.wasp" {1, 6} + app YourAppName { + wasp: { + version: "^0.13.2" + }, + + title: "Your App Name", + ``` + :::caution[Restart Your App] + 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 `app.head` (even if you don't have a custom domain yet, put one you would like to have, as this won't affect development). +- [ ] Update `app.emailSender.defaultFrom.name` 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 - `app.auth.methods` + - [ ] If you're not using `email` Auth method, remove the routes/pages `RequestPasswordReset`, `PasswordReset`, and `EmailVerification` + - [ ] Email Sending - `app.emailSender`, `job emailChecker` + - [ ] Plausible analytics - `app.head` + - [ ] File Uploading - `entity File`, `route FileUploadRoute`, `action createFile`, `query getAllFilesByUser`, `getDownloadFileSignedURL` +- [ ] 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 `app.head` of the `main.wasp` file. +- [ ] 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 `tailwind.config.cjs`. **Be aware that the current custom global styles defined already are mostly used in the app's Admin Dashboard!** + +#### Customizing the Analytics & Admin Dashboard +- [ ] If you're using Plausible, update the `app.head` with your Plausible domain. +- [ ] Update the `calculateDailyStats` function in `src/server/workers/calculateDailyStats.ts` to pull the stats from the analytics provider you've chosen (Plausible or Google Analytics). +- [ ] Change the cron schedule in the `dailyStatsJob` in the `main.wasp` 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 Repo 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](https://github.com/wasp-lang/open-saas/tree/main/.github/workflows)) + +## What's next? + +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. diff --git a/opensaas-sh/blog/src/env.d.ts b/opensaas-sh/blog/src/env.d.ts new file mode 100644 index 000000000..acef35f17 --- /dev/null +++ b/opensaas-sh/blog/src/env.d.ts @@ -0,0 +1,2 @@ +///