Next.js Supabase V3 (#463)

Version 3 of the kit:
- Radix UI replaced with Base UI (using the Shadcn UI patterns)
- next-intl replaces react-i18next
- enhanceAction deprecated; usage moved to next-safe-action
- main layout now wrapped with [locale] path segment
- Teams only mode
- Layout updates
- Zod v4
- Next.js 16.2
- Typescript 6
- All other dependencies updated
- Removed deprecated Edge CSRF
- Dynamic Github Action runner

docs/troubleshooting/troubleshooting-authentication.mdoc

@@ -0,0 +1,24 @@
+---
+status: "published"
+title: 'Troubleshooting authentication issues in the Next.js Supabase kit'
+label: 'Authentication'
+order: 2
+description: 'Troubleshoot issues related to authentication in the Next.js Supabase SaaS kit'
+---
+
+
+## Supabase redirects to localhost instead of my website URL
+
+This is most likely an issue related to not having set up the Authentication URL in the Supabase settings as describe in [the going to production guide](../going-to-production/supabase);
+
+## Cannot Receive Emails from Supabase
+
+This issue may arise if you have not setup an SMTP provider from within Supabase.
+
+Supabase's own SMTP provider has low limits and low deliverability, therefore you must set up your own - and only use the default Supabase's one for testing purposes.
+
+## Cannot sign in with oAuth provider
+
+This is most likely a settings issues from within the Supabase dashboard or in the provider's settings.
+
+Please [read Supabase's documentation](https://supabase.com/docs/guides/auth/social-login) on how to set up third-party providers.

docs/troubleshooting/troubleshooting-billing.mdoc

@@ -0,0 +1,43 @@
+---
+status: "published"
+title: 'Troubleshooting billing issues in the Next.js Supabase kit'
+label: 'Billing'
+order: 3
+description: 'Troubleshoot issues related to billing in the Next.js Supabase SaaS kit'
+---
+
+## Cannot create a Checkout
+
+This happen in the following cases:
+
+1. **The environment variables are not set correctly**: Please make sure you have set the following environment variables in your `.env` file if locally - or in your hosting provider's dashboard if in production
+2. **The plan IDs used are incorrect**: Make sure to use the exact plan IDs as they are in the payment provider's dashboard.
+
+## The Database is not updated after subscribing to a plan
+
+This may happen if the webhook is not set up correctly. Please make sure you have set up the webhook in the payment provider's dashboard and that the URL is correct.
+
+Common issues include:
+1. **The webhook is not set up correctly**: Please make sure you have set up the webhook in the payment provider's dashboard and that the URL is correct.
+2. **The plan IDs used are incorrect**: Make sure to use the exact plan IDs as they are in the payment provider's dashboard.
+3. **The environment variables are not set correctly**: Please make sure you have set the following environment variables in your `.env` file if locally - or in your hosting provider's dashboard if in production
+
+### Locally
+
+If working locally, make sure that:
+
+1. **Stripe**: If using Stripe, that the Stripe CLI is up and running
+2. **Lemon Squeezy**: If using Lemon Squeezy, that the webhook set in Lemon Squeezy is correct and that the server is running. Additionally, make sure the proxy is set up correctly if you are testing locally (see the Lemon Squeezy documentation for more information).
+
+### Production
+
+If working in production, make sure that:
+
+- The Stripe/Lemon Squeezy webhooks are set up correctly and are being sent to the correct URL. The URL must be publicly accessible. If the URL is not publicly accessible, you will not be able to receive webhooks from Stripe.
+- If the webhooks are being sent, please read the logs in your hosting provider to see if there are any errors related to webhooks.
+- If after reading the logs, the webhooks are not being sent, please contact support by posting relevant information in the Support Ticket.
+
+When opening a support ticket, please make sure to include:
+1. The logs being sent from Stripe in the Stripe Dashboard
+2. The logs in your hosting provider
+3. Any error messages you may have received

docs/troubleshooting/troubleshooting-deployment.mdoc

@@ -0,0 +1,15 @@
+---
+status: "published"
+title: 'Troubleshooting deployment issues in the Next.js Supabase kit'
+label: 'Deployment'
+order: 4
+description: 'Troubleshoot issues related to deploying the application in the Next.js Supabase SaaS kit'
+---
+
+## The deployment build fails
+
+This is most likely an issue related to the environment variables not being set correctly in the deployment environment. Please analyse the logs of the deployment provider to see what is the issue.
+
+The kit is very defensive about incorrect environment variables, and will throw an error if any of the required environment variables are not set. In this way - the build will fail if the environment variables are not set correctly - instead of deploying a broken application.
+
+If you are deploying to Vercel, [please follow this guide](../going-to-production/vercel).

docs/troubleshooting/troubleshooting-emails.mdoc

@@ -0,0 +1,17 @@
+---
+status: "published"
+title: 'Troubleshooting emails issues in the Next.js Supabase kit'
+label: 'Emails'
+order: 5
+description: 'Troubleshoot issues related to emails in the Next.js Supabase SaaS kit'
+---
+
+To troubleshoot emails issues in the Next.js Supabase kit, please make sure to:
+
+1. **Correct Credentials**: please make sure you have setup the correct credentials in your environment variables. Refer to the [emails guide](../emails/email-configuration) for more information.
+2. **Your domain is verified**: make sure your domain is verified in your Email provider
+3. **The Database Webhooks are configured**: make sure you have configured the Database Webhooks in your Supabase project. Refer to the [Supabase deployment guide](../going-to-production/supabase) for more information. Make sure to read Webhooks are pointing to the correct URL and use the correct shared secret.
+4. **The Webhooks use a public URL**: make sure the webhooks use a public URL and not behind authentication (such as a Vercel Preview URL).
+5. **Read the Logs**: please verify your server logs in your hosting provider to see if there are any errors related to emails.
+
+If you have done all the above and still having issues, please open a Support Ticket in Discord.

docs/troubleshooting/troubleshooting-installation.mdoc

@@ -0,0 +1,37 @@
+---
+status: "published"
+
+title: 'Troubleshooting installation issues in the Next.js Supabase SaaS kit'
+label: 'Installation'
+order: 1
+description: 'Troubleshoot issues related to installing the Next.js Supabase SaaS kit'
+---
+
+
+## Cannot clone the repository
+
+Issues related to cloning the repository are usually related to a Git misconfiguration in your local machine. The commands displayed in this guide using SSH: these will work only if you have setup your SSH keys in Github.
+
+If you run into issues, [please make sure you follow this guide to set up your SSH key in Github](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
+
+If this also fails, please use HTTPS instead. You will be able to see the commands in the repository's Github page under the "Clone" dropdown.
+
+Please also make sure that the account that accepted the invite to Makerkit, and the locally connected account are the same.
+
+## The Next.js dev server does not start
+
+This may happen due to some issues in the packages. Try to clean the workspace and reinstall everything again:
+
+```bash
+pnpm run clean:workspaces
+pnpm run clean
+pnpm i
+```
+
+You can now retry running the dev server.
+
+## Supabase does not start
+
+If you cannot run the Supabase local development environment, it's likely you have not started Docker locally. Supabase requires Docker to be installed and running.
+
+Please make sure you have installed Docker (or compatible software such as Colima, Orbstack) and that is running on your local machine.

docs/troubleshooting/troubleshooting-license.mdoc

@@ -0,0 +1,60 @@
+---
+status: "published"
+title: 'Troubleshooting license issues in the Next.js Supabase kit'
+label: 'License'
+order: 6
+description: 'Troubleshoot issues related to license in the Next.js Supabase SaaS kit'
+---
+
+## Email from GitHub not received
+
+If you haven't received the GitHub invitation email after purchasing a Makerkit license, this is almost always due to GitHub's email delivery behavior.
+
+### Understanding GitHub's Email Behavior
+
+**Important:** GitHub sends repository invitations to your **primary email address** associated with your GitHub account, not the email you used for your Makerkit purchase or payment or where the invitation was sent.
+
+### How to Find Your GitHub Primary Email
+
+1. Go to [GitHub Email Settings](https://github.com/settings/emails)
+2. Look for the email marked as "Primary"
+3. Check the inbox of that primary email address for the Makerkit repository invitation
+
+### Common Scenarios
+
+#### Scenario 1: Different Email for Purchase vs. GitHub
+
+If you purchased Makerkit with `work@company.com` but your GitHub primary email is `personal@gmail.com`, the invitation will be sent to `personal@gmail.com`.
+
+#### Scenario 2: Multiple GitHub Email Addresses
+
+If you have multiple email addresses in your GitHub account but only one is set as "Primary", only that primary email will receive the invitation.
+
+### Steps to Resolve
+
+1. **Check Your GitHub Primary Email**
+   - Visit [GitHub Email Settings](https://github.com/settings/emails) and make sure your primary email is set correctly
+   - Check the inbox (including spam/junk folders) of your primary email address
+2. **Change Your Primary Email (if needed)**
+   - If you want invitations sent to a different email:
+     - Add the desired email to your GitHub account if not already added
+     - Verify the email address
+     - Set it as your primary email
+     - Contact Makerkit support to resend the invitation
+3. **Check Spam/Junk Folders**
+   - GitHub invitation emails sometimes end up in spam
+   - Search for emails from `notifications@github.com`
+4. **Check GitHub Organizations**
+   - Visit [GitHub Notifications](https://github.com/settings/organizations)
+   - Organizations may also appear there
+
+### Still Can't Find the Invitation?
+
+If you've checked your primary email and still haven't received the invitation:
+
+1. Contact Makerkit support with:
+   - Your GitHub username
+   - Your GitHub primary email address
+   - Confirmation that you've checked spam folders
+
+Support will resend the invitation to ensure you receive it.

docs/troubleshooting/troubleshooting-module-not-found.mdoc

@@ -0,0 +1,62 @@
+---
+status: "published"
+title: 'Troubleshooting module not found issues in the Next.js Supabase kit'
+label: 'Modules not found'
+order: 6
+description: 'Troubleshoot issues related to modules not found in the Next.js Supabase SaaS kit'
+---
+
+Let's walk through common "Module not found" errors and how to fix them in your Makerkit project.
+
+This issue is mostly related to either dependency installed in the wrong package or issues with the file system.
+
+### 1. Windows Paths issues
+
+Windows has a limitation for the maximum path length. If you're running into issues with paths, you can try the following:
+
+1. Move the project closer to the root of your drive
+2. Use a shorter name for the project's folder name
+3. Please Please Please use WSL2 instead of Windows
+
+### 2. Windows OneDrive Conflicts
+
+OneDrive can cause file system issues with Node.js projects. If you're using Windows with OneDrive:
+
+1. Move your project outside of OneDrive-synced folders
+2. Or disable OneDrive sync for your development folder
+
+
+### 3. Dependency Installation Issues
+
+The most common cause is incorrect dependency installation. Here's how to fix it:
+
+```bash
+# First, clean your workspace
+pnpm run clean:workspaces
+pnpm run clean
+
+# Reinstall dependencies
+pnpm install
+```
+
+If you're adding new dependencies, make sure to install them in the correct package:
+
+```bash
+# For main app dependencies
+pnpm install my-package --filter web
+
+# For a specific package
+pnpm install my-package --filter @kit/ui
+```
+
+For example, if you're using the dependency in the `@kit/ui` package, you should install it in the `@kit/ui` package:
+
+```bash
+pnpm add my-package --filter "@kit/ui"
+```
+
+If it's in the main app, you should install it in the main app:
+
+```bash
+pnpm add my-package --filter web
+```