alezmad/whyrating
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: whyrating - initial project from turbostarter boilerplate

Browse Source
This commit is contained in:
Alejandro Gutiérrez
2026-02-04 01:54:52 +01:00
commit 5cdc07cd39
1618 changed files with 338230 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
.context/turbostarter-framework-context/sections/extension/ai.md Normal file
View File

@@ -0,0 +1,84 @@
---
title: AI
description: Leverage AI in your TurboStarter extension.
url: /docs/extension/ai
---
# AI
When it comes to AI within the browser extension, we can differentiate two approaches:
* **Server + client**: Traditional implementation, same as for [web](/docs/web/ai/overview) and [mobile](/docs/mobile/ai), used to stream responses generated on the server to the client.
* **Chrome built-in AI**: An [experimental implementation](https://developer.chrome.com/docs/ai/built-in) of [Gemini Nano](https://blog.google/technology/ai/google-gemini-ai/#performance) that's built into new versions of the Google Chrome browser.
We recommend relying more on the traditional server + client approach, as it's more versatile and easier to implement. Chrome's built-in AI is a nice feature, but it's still experimental and has some limitations.
Of course, you can always implement a *hybrid* approach which combines both solutions to achieve the best results.
## Server + client
The traditional usage of AI integration in the browser extension is the same as for [web app](/docs/web/ai/configuration#client-side) and [mobile app](/docs/mobile/ai). We use the exact same [API endpoint](/docs/web/ai/configuration#api-endpoint), and we leverage streaming to display answers incrementally to the user as they're generated.
```tsx title="main.tsx"
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";
const Popup = () => {
const { messages } = useChat({
transport: new DefaultChatTransport({
api: "/api/ai/chat",
}),
});
return (
<div>
{messages.map((message) => (
<div key={message.id}>
{message.parts.map((part, i) => {
switch (part.type) {
case "text":
return <div key={`${message.id}-${i}`}>{part.text}</div>;
}
})}
</div>
))}
</div>
);
};
export default Popup;
```
It's the most reliable and recommended way to use AI in the browser extension. Feel free to reuse or modify it to suit your specific needs.
## Chrome built-in AI
<Callout type="warn">
Chrome's implementation of [built-in AI with Gemini Nano](https://developer.chrome.com/docs/ai/built-in) is experimental and will change as they test and address feedback.
</Callout>
Chrome's built-in AI is a preview feature. To use it, you need Chrome version 127 or greater and you must enable these flags:
* [chrome://flags/#prompt-api-for-gemini-nano](chrome://flags/#prompt-api-for-gemini-nano): `Enabled`
* [chrome://flags/#optimization-guide-on-device-model](chrome://flags/#optimization-guide-on-device-model): `Enabled BypassPrefRequirement`
* [chrome://components/](chrome://components/): Click `Optimization Guide On Device Model` to download the model.
Once enabled, you'll be able to use `window.ai` to access the built-in AI and do things like this:
![Chrome built-in AI](/images/docs/extension/ai.gif)
You can even use a [dedicated provider](https://sdk.vercel.ai/providers/community-providers/chrome-ai) from the Vercel AI SDK ecosystem to simplify its usage. Please remember that this API is still in its early stages and might change in the future.
<Callout title="Available in every extension context!">
The best thing is that you can use this API in every part of your extension, e.g., popup, background service worker, etc.
It's completely safe to use on the client-side, as we're not exposing any sensitive data to the user (such as the API key in the traditional server + client approach).
</Callout>
To learn more, please check out the official [Chrome documentation](https://developer.chrome.com/docs/ai/built-in) and the articles listed below.
<Cards>
<Card href="https://developer.chrome.com/docs/ai/built-in" title="Get started with built-in AI" description="developer.chrome.com" />
<Card href="https://developer.chrome.com/docs/extensions/ai" title="Extensions and AI" description="developer.chrome.com" />
</Cards>

92
.context/turbostarter-framework-context/sections/extension/analytics/configuration.md Normal file
View File

@@ -0,0 +1,92 @@
---
title: Configuration
description: Learn how to configure extension analytics in TurboStarter.
url: /docs/extension/analytics/configuration
---
# Configuration
The `@turbostarter/analytics-extension` package offers a streamlined and flexible approach to tracking events in your TurboStarter extension using various analytics providers. It abstracts the complexities of different analytics services and provides a consistent interface for event tracking.
In this section, we'll guide you through the configuration process for each supported provider.
Note that the configuration is validated against a schema, so you'll see error messages in the console if anything is misconfigured.
## Providers
Below, you'll find detailed information on how to set up and use each supported provider. Choose the one that best suits your needs and follow the instructions in the respective accordion section.
<Accordions>
<Accordion title="Google Analytics" id="google-analytics">
To use Google Analytics as your analytics provider, you need to [create a Google Analytics account](https://analytics.google.com/) and [set up a property](https://support.google.com/analytics/answer/9304153).
Next, add a data stream in your Google Analytics account settings:
1. Navigate to [Google Analytics](https://analytics.google.com/).
2. In the *Admin* section, under *Data collection and modification*, click on *Data Streams*.
3. Click *Add stream*.
4. Select *Web* as the platform.
5. Enter the required details for the stream (at minimum, provide a name and website URL).
6. Click *Create stream*.
After creating the stream, you'll need two pieces of information:
1. Your [Measurement ID](https://support.google.com/analytics/answer/12270356) (it should look like `G-XXXXXXXXXX`):
![Google Analytics Measurement ID](/images/docs/web/analytics/google/id.png)
2. Your [Measurement Protocol API secret](https://support.google.com/analytics/answer/9814495):
![Google Analytics Measurement Protocol API secret](/images/docs/web/analytics/google/api-secret.png)
Set these values in your `.env.local` file in the `apps/extension` directory and in your CI/CD provider secrets:
```dotenv
VITE_GOOGLE_ANALYTICS_MEASUREMENT_ID="your-measurement-id"
VITE_GOOGLE_ANALYTICS_SECRET="your-measurement-protocol-api-secret"
```
Also, make sure to activate the Google Analytics provider as your analytics provider by updating the exports in:
```ts title="index.ts"
// [!code word:google-analytics]
export * from "./google-analytics";
export * from "./google-analytics/env";
```
To customize the provider, you can find its definition in `packages/analytics/extension/src/providers/google-analytics` directory.
For more information, please refer to the [Google Analytics documentation](https://developers.google.com/analytics).
![Google Analytics dashboard](/images/docs/web/analytics/google/dashboard.jpg)
</Accordion>
<Accordion title="PostHog" id="posthog">
<Callout type="info" title="You can also use it for monitoring!">
PostHog is also one of pre-configured providers for [monitoring](/docs/extension/monitoring/overview) in TurboStarter. You can learn more about it [here](/docs/extension/monitoring/posthog).
</Callout>
To use PostHog as your analytics provider, you need to configure a PostHog instance. You can obtain the [Cloud](https://app.posthog.com/signup) instance by [creating an account](https://app.posthog.com/signup) or [self-host](https://posthog.com/docs/self-host) it.
Then, create a project and, based on your [project settings](https://app.posthog.com/project/settings), fill the following environment variables in your `.env.local` file in `apps/extension` directory and your CI/CD provider secrets:
```dotenv
VITE_POSTHOG_KEY="your-posthog-api-key"
VITE_POSTHOG_HOST="your-posthog-instance-host"
```
Also, make sure to activate the PostHog provider as your analytics provider by updating the exports in:
```ts title="index.ts"
// [!code word:posthog]
export * from "./posthog";
export * from "./posthog/env";
```
To customize the provider, you can find its definition in `packages/analytics/extension/src/providers/posthog` directory.
For more information, please refer to the [PostHog documentation](https://posthog.com/docs/advanced/browser-extension).
![PostHog dashboard](/images/docs/web/analytics/posthog.png)
</Accordion>
</Accordions>

59
.context/turbostarter-framework-context/sections/extension/analytics/overview.md Normal file
View File

@@ -0,0 +1,59 @@
---
title: Overview
description: Get started with extension analytics in TurboStarter.
url: /docs/extension/analytics/overview
---
# Overview
When it comes to extension analytics, we can distinguish between two types:
* **Store listing analytics**: Used to track the performance of your extension's store listing (e.g., how many people have viewed your extension in the store or how many have installed it).
* **In-extension analytics**: Tracks user actions within your extension (e.g., how many users triggered your popup, how many users modified extension settings, etc.).
The `@turbostarter/analytics-extension` package provides a set of tools to easily implement both types of analytics in your extension.
## Store listing analytics
Interpreting your extension's store listing metrics can help you evaluate how changes to your extension and store listing affect conversion rates. For example, you can identify countries with a high number of visitors to prioritize supporting languages for those regions.
While each store implements a different set of metrics, there are some common ones you should be aware of:
* **Active installs**: The number of users who have installed your extension.
* **Active users**: The number of users who have used your extension.
* **Page views**: The number of times users have viewed your extension's detail page on the respective store.
To track more detailed metrics, you can opt in to Google Analytics in the Chrome Web Store's developer dashboard.
You can find this option under *Additional metrics* on the *Store listing* tab of your extension's control panel:
![Chrome Web Store - Store listing - Additional metrics](/images/docs/extension/analytics/opt-in-analytics.png)
<Callout>
The Chrome Web Store manages the account for you and makes the data available
in the Google Analytics dashboard.
</Callout>
By enabling this feature, you can optimize your extension's store listing based on metrics such as bounce rate, time on page, and more. This can lead to more installs and ultimately more users for your extension.
To learn more about the limitations of this type of analytics and how to adjust event details, please refer to the following sections in the official documentation:
<Cards>
<Card title="Analyze your store listing metrics" description="developer.chrome.com" href="https://developer.chrome.com/docs/webstore/metrics" />
<Card title="Use your Google Analytics account with the Chrome Web Store" description="developer.chrome.com" href="https://developer.chrome.com/docs/webstore/google-analytics" />
</Cards>
## In-extension analytics
TurboStarter comes with built-in support for tracking in-extension analytics. To learn more about each supported provider and how to configure them, see their respective sections:
<Cards>
<Card title="Google Analytics" href="/docs/extension/analytics/configuration#google-analytics" />
<Card title="PostHog" href="/docs/extension/analytics/configuration#posthog" />
</Cards>
All configuration and setup is built-in with a unified API, allowing you to switch between providers by simply changing the exports. You can even introduce your own provider without breaking any tracking-related logic.
In the following sections, we'll cover how to set up each provider and how to track events in your extension.

80
.context/turbostarter-framework-context/sections/extension/analytics/tracking.md Normal file
View File

@@ -0,0 +1,80 @@
---
title: Tracking events
description: Learn how to track events in your TurboStarter extension.
url: /docs/extension/analytics/tracking
---
# Tracking events
The strategy for tracking events that every provider has to implement is extremely simple:
```ts
export type AllowedPropertyValues = string | number | boolean;
type TrackFunction = (
event: string,
data?: Record<string, AllowedPropertyValues>,
) => void;
export interface AnalyticsProviderStrategy {
track: TrackFunction;
}
```
<Callout>
You don't need to worry much about this implementation, as all the providers are already configured for you. However, it's useful to be aware of this structure if you plan to add your own custom provider.
</Callout>
As shown above, each provider must supply the `track` function. This function is responsible for sending event data to the provider.
To track an event in any part of your extension, simply call the `track` method, passing the event name and an optional data object:
```tsx title="main.tsx"
import { track } from "@turbostarter/analytics-extension";
const Popup = () => {
return (
<button onClick={() => track("popup.button.click", { country: "US" })}>
Track event
</button>
);
};
export default Popup;
```
## Identifying users
Linking events to specific users enables you to build a full picture of how they're using your product across different sessions, devices, and platforms.
For identification purposes, we're extending the strategy with the `identify` and `reset` methods. They are optional and only needed if you want to identify users in your app and associate their actions with a specific user ID.
```ts
type IdentifyFunction = (
userId: string,
traits?: Record<string, AllowedPropertyValues>,
) => void;
export interface AnalyticsProviderClientStrategy {
identify: IdentifyFunction;
reset: () => void;
}
```
To identify users, call the `identify` method, passing the user's ID and an optional traits object:
```tsx
import { identify } from "@turbostarter/analytics-extension";
identify("user-123", { name: "John Doe" });
```
This will associate all future events with the user's ID, allowing you to track user behavior and gain valuable insights into your application's usage patterns.
<Callout title="Configured by default!">
The `identify` method is configured out-of-the-box to react on changes to the user's authentication state.
When the user is authenticated, the `identify` method will be called with the user's ID and the user's traits. When the user is logged out, the `reset` method will be called to clear the existing user identification.
</Callout>
Congratulations! You've now mastered event tracking in your TurboStarter extension. With this knowledge, you're well-equipped to analyze user behaviors and gain valuable insights into your extension's usage patterns. Happy analyzing! 📊

197
.context/turbostarter-framework-context/sections/extension/api/client.md Normal file
View File

@@ -0,0 +1,197 @@
---
title: Using API client
description: How to use API client to interact with the API.
url: /docs/extension/api/client
---
# Using API client
In browser extension code, you can only access the API client from the **client-side.**
When you create a new component or piece of your extension and want to fetch some data, you can use the API client to do so.
## Creating a client
We're creating a client-side API client in `apps/extension/src/lib/api/index.tsx` file. It's a simple wrapper around the [@tanstack/react-query](https://tanstack.com/query/latest/docs/framework/react/overview) that fetches or mutates data from the API.
It also requires wrapping your views in a `QueryClientProvider` component to provide the API client to the rest of the components.
We recommend to create a separate layout file, which will be used to wrap your pages. TurboStarter comes with a `layout.tsx` file in the `modules/common/layout` folder, which you can use as a template:
```tsx title="layout.tsx"
export const Layout = ({
children,
loadingFallback,
errorFallback,
}: LayoutProps) => {
return (
<ErrorBoundary fallback={errorFallback}>
<Suspense fallback={loadingFallback}>
<QueryClientProvider>{children}</QueryClientProvider>
</Suspense>
</ErrorBoundary>
);
};
```
Remember that every part of your extension will be mounted as a **separate** React component, so you need to wrap each of them in the `QueryClientProvider` component if you want to use the API client inside:
```tsx title="app/popup/main.tsx"
import { Layout } from "~/modules/common/layout/layout";
export default function Popup() {
return <Layout>{/* your popup code here */}</Layout>;
}
```
<Callout type="warn" title="Ensure correct API url">
Inside the `apps/extension/src/lib/api/index.tsx` we're calling a function to get base url of your api, so make sure it's set correctly (especially on production) and your web api endpoint is corresponding with the name there.
```tsx title="index.tsx"
const getBaseUrl = () => {
return env.VITE_SITE_URL;
};
```
As you can see we're mostly relying on the [environment variables](/docs/extension/configuration/environment-variables) to get it, so there shouldn't be any issues with it, but in case, please be aware where to find it 😉
</Callout>
## Queries
Of course, everything comes already configured for you, so you just need to start using `api` in your components/screens.
For example, to fetch the list of posts you can use the `useQuery` hook:
```tsx title="posts.tsx"
import { api } from "~/lib/api";
export const Posts = () => {
const { data: posts, isLoading } = useQuery({
queryKey: ["posts"],
queryFn: async () => {
const response = await api.posts.$get();
if (!response.ok) {
throw new Error("Failed to fetch posts!");
}
return response.json();
},
});
if (isLoading) {
return <p>Loading...</p>;
}
/* do something with the data... */
return (
<div>
<p>{JSON.stringify(posts)}</p>
</div>
);
};
```
It's using the `@tanstack/react-query` [useQuery API](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery), so you shouldn't have any troubles with it.
<Cards>
<Card title="Hono RPC" description="hono.dev" href="https://hono.dev/docs/guides/rpc" />
<Card title="useQuery hook | Tanstack Query" description="tanstack.com" href="https://tanstack.com/query/latest/docs/framework/react/reference/useQuery" />
</Cards>
## Mutations
If you want to perform a mutation in your extension code, you can use the `useMutation` hook that comes straight from the integration with [Tanstack Query](https://tanstack.com/query):
```tsx title="modules/popup/form.tsx"
import { api } from "~/lib/api";
export const CreatePost = () => {
const queryClient = useQueryClient();
const { mutate } = useMutation({
mutationFn: async (post: PostInput) => {
const response = await api.posts.$post(post);
if (!response.ok) {
throw new Error("Failed to create post!");
},
},
onSuccess: () => {
toast.success("Post created successfully!");
queryClient.invalidateQueries({ queryKey: ["posts"] });
},
});
return <form onSubmit={onSubmit(mutate)} />;
};
```
Here, we're also invalidating the query after the mutation is successful. This is a very important step to make sure that the data is updated in the UI.
<Cards>
<Card title="useMutation hook" description="tanstack.com" href="https://tanstack.com/query/latest/docs/framework/react/reference/useMutation" />
<Card title="Query invalidation" description="tanstack.com" href="https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation" />
</Cards>
## Handling responses
As you can see in the examples above, the [Hono RPC](https://hono.dev/docs/guides/rpc) client returns a plain `Response` object, which you can use to get the data or handle errors. However, implementing this handling in every query or mutation can be tedious and will introduce unnecessary boilerplate in your codebase.
That's why we've developed the `handle` function that unwraps the response for you, handles errors, and returns the data in a consistent format. You can safely use it with any procedure from the API client:
<Tabs items={["Queries", "Mutations"]}>
<Tab value="Queries">
```tsx
// [!code word:handle]
import { handle } from "@turbostarter/api/utils";
import { api } from "~/lib/api";
export const Posts = () => {
const { data: posts, isLoading } = useQuery({
queryKey: ["posts"],
queryFn: handle(api.posts.$get),
});
if (isLoading) {
return <p>Loading...</p>;
}
/* do something with the data... */
return (
<div>
<p>{JSON.stringify(posts)}</p>
</div>
);
};
```
</Tab>
<Tab value="Mutations">
```tsx
// [!code word:handle]
import { handle } from "@turbostarter/api/utils";
import { api } from "~/lib/api/client";
export const CreatePost = () => {
const queryClient = useQueryClient();
const { mutate } = useMutation({
mutationFn: handle(api.posts.$post),
onSuccess: () => {
toast.success("Post created successfully!");
queryClient.invalidateQueries({ queryKey: ["posts"] });
},
});
return <form onSubmit={onSubmit(mutate)} />;
};
```
</Tab>
</Tabs>
With this approach, you can focus on the business logic instead of repeatedly writing code to handle API responses in your browser extension components, making your extension's codebase more readable and maintainable.
The same error handling and response unwrapping benefits apply whether you're building web, mobile, or extension interfaces - allowing you to keep your data fetching logic consistent across all platforms.

45
.context/turbostarter-framework-context/sections/extension/api/overview.md Normal file
View File

@@ -0,0 +1,45 @@
---
title: Overview
description: Get started with the API.
url: /docs/extension/api/overview
---
# Overview
<Callout type="error" title="API deployment required">
To enable communication between your WXT extension and the server in a production environment, the web application with Hono API must be deployed first.
<Cards>
<Card title="API" description="Learn more about the API." href="/docs/web/api/overview" />
<Card title="Web deployment" description="Deploy your web application to production." href="/docs/web/deployment/checklist" />
</Cards>
</Callout>
TurboStarter is designed to be a scalable and production-ready full-stack starter kit. One of its core features is a dedicated and extensible API layer. To enable this in a type-safe manner, we chose [Hono](https://hono.dev) as the API server and client library.
<Callout title="Why Hono?">
Hono is a small, simple, and ultrafast web framework that gives you a way to
define your API endpoints with full type safety. It provides built-in
middleware for common needs like validation, caching, and CORS. It also
includes an [RPC client](https://hono.dev/docs/guides/rpc) for making
type-safe function calls from the frontend. Being edge-first, it's optimized
for serverless environments and offers excellent performance.
</Callout>
All API endpoints and their resolvers are defined in the `packages/api/` package. Here you will find a `modules` folder that contains the different feature modules of the API. Each module has its own folder and exports all its resolvers.
For each module, we create a separate Hono route in the `packages/api/index.ts` file and aggregate all sub-routers into one main router.
The API is then exposed as a route handler that will be provided as a Next.js API route:
```ts title="apps/web/src/app/api/[...route]/route.ts"
import { handle } from "hono/vercel";
import { appRouter } from "@turbostarter/api";
const handler = handle(appRouter);
export { handler as GET, handler as POST };
```
Learn more about how to use the API in your browser extension code in the following sections:

46
.context/turbostarter-framework-context/sections/extension/auth/overview.md Normal file
View File

@@ -0,0 +1,46 @@
---
title: Overview
description: Learn how to authenticate users in your extension.
url: /docs/extension/auth/overview
---
# Overview
TurboStarter uses [Better Auth](https://better-auth.com) to handle authentication. It's a secure, production-ready authentication solution that integrates seamlessly with many frameworks and provides enterprise-grade security out of the box.
<Callout title="Why Better Auth?">
One of the core principles of TurboStarter is to do things **as simple as possible**, and to make everything **as performant as possible**.
Better Auth provides an excellent developer experience with minimal configuration required, while maintaining enterprise-grade security standards. Its framework-agnostic approach and focus on performance makes it the perfect choice for TurboStarter.
Recently, Better Auth [announced](https://www.better-auth.com/blog/authjs-joins-better-auth) an incorporation of [Auth.js (27k+ stars on Github)](https://authjs.dev/), making it even more powerful and flexible.
</Callout>
![Better Auth](/images/docs/better-auth.png)
You can read more about Better Auth in the [official documentation](https://better-auth.com/docs).
<Callout type="info" title="IMPORTANT: Shared authentication">
To keep things simple and secure, **the extension shares the same authentication session with your web app.**
This is a common approach used by popular services like [Notion](https://www.notion.so) and [Google Workspace](https://workspace.google.com/). The benefits include:
* Users only need to sign in once through the web app
* The extension automatically inherits the authenticated session
* Sign out actions are synchronized across platforms
* Reduced security surface area and complexity
</Callout>
Before setting up extension authentication, make sure to first [configure authentication for your web app](/docs/web/auth/overview) and then head back to the extension code.
The following sections cover everything you need to know about authentication in your extension:
<Cards>
<Card title="Configuration" description="Configure authentication for your application." href="/docs/web/auth/configuration" />
<Card title="User flow" description="Discover the authentication flow in Turbostarter." href="/docs/web/auth/flow" />
<Card title="OAuth" description="Get started with social authentication." href="/docs/web/auth/oauth" />
<Card title="Session" description="Learn how to manage auth session in your extension." href="/docs/extension/auth/session" />
</Cards>

123
.context/turbostarter-framework-context/sections/extension/auth/session.md Normal file
View File

@@ -0,0 +1,123 @@
---
title: Session
description: Learn how to manage the user session in your extension.
url: /docs/extension/auth/session
---
# Session
We're not implementing fully-featured auth flow in the extension. Instead, **we're sharing the same auth session with the web app.**
It's a common practice in the industry used e.g. by [Notion](https://www.notion.so) and [Google Workspace](https://workspace.google.com/).
That way, when the user is signed in to the web app, the extension can use the same session to authenticate the user, so he doesn't have to sign in again. Also signing out from the extension will affect both platforms.
<Callout title="Remember to add your extension scheme as trusted origin">
For browser extensions, we need to define an [authentication trusted origin](https://www.better-auth.com/docs/reference/security#trusted-origins) using an extension scheme.
Extension schemes (like `chrome-extension://...`) are used for redirecting users to specific screens after authentication and sharing the auth session with the web app.
To find your extension ID, open Chrome and go to `chrome://extensions/`, enable Developer Mode in the top right, and look for your extension's ID. Then add it to your auth server configuration:
```ts title="server.ts"
export const auth = betterAuth({
...
trustedOrigins: ["chrome-extension://your-extension-id"],
...
});
```
Adding your extension scheme to the trusted origins list is crucial for security - it prevents CSRF attacks and blocks malicious open redirects by ensuring only requests from approved origins (your extension) are allowed through.
[Read more about auth security in Better Auth's documentation.](https://www.better-auth.com/docs/reference/security)
</Callout>
## Cookies
When the user signs in to the [web app](/docs/web) through our [Better Auth API](/docs/web/auth/configuration#api), web app is setting the cookie with the session token under your app's domain, which is later used to validate the session on the server.
You can find your cookie in *Cookies* tab in the browser's developer tools (remember to be logged in to the app to check it):
![Session cookie](/images/docs/extension/auth/cookie.png)
To enable your extension to read the cookie and that way share the session with the web app, you need to set the `cookies` permission in the `wxt.config.ts` under `manifest.permissions` field:
```ts title="wxt.config.ts"
export default defineConfig({
manifest: {
permissions: ["cookies"],
},
});
```
And to be able to read the cookie from your app url, you need to set `host_permissions`, which will include your app url:
```ts title="wxt.config.ts"
export default defineConfig({
manifest: {
host_permissions: ["http://localhost/*", "https://your-app-url.com/*"],
},
});
```
Then you would be able to share the cookie with API requests and also read its value using `browser.cookies` API.
<Callout title="Avoid &#x22;<all_urls>&#x22;" type="warn">
Avoid using `<all_urls>` in `host_permissions`. It affects all urls and may cause security issues, as well as a [rejection](https://developer.chrome.com/docs/webstore/review-process#review-time-factors) from the destination store.
</Callout>
<Cards>
<Card title="Declare permissions" href="https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions" description="developer.chrome.com" />
<Card title="chrome.cookies" href="https://developer.chrome.com/docs/extensions/reference/api/cookies" description="developer.chrome.com" />
</Cards>
## Reading session
You **don't** need to worry about reading, parsing, or validating the session cookie. TurboStarter comes with a pre-built solution that ensures your session is correctly shared with the web app.
It also ensures that appropriate cookies are passed to [API](/docs/web/api/overview) requests, so you can safely use [protected endpoints](/docs/web/api/protected-routes) (that require authentication) in your extension.
To get session details in your extension code (e.g., inside a popup window), you can leverage the `useSession` hook provided by the [auth client](https://www.better-auth.com/docs/basic-usage#client-side) (which is also used in the web and mobile apps):
```tsx title="user.tsx"
import { authClient } from "~/lib/auth";
const User = () => {
const {
data: { user, session },
isPending,
} = authClient.useSession();
if (isPending) {
return <p>Loading...</p>;
}
/* do something with the session data... */
return <p>{user?.email}</p>;
};
```
That's how you can access user details right in your extension.
## Signing out
Signing out from the extension also involves using the well-known `signOut` function that is derived from our [auth client](https://www.better-auth.com/docs/basic-usage#signout):
```tsx title="logout.tsx"
import { authClient } from "~/lib/auth";
export const Logout = () => {
return <button onClick={() => authClient.signOut()}>Log out</button>;
};
```
The session is automatically invalidated, so the next use of `useSession` or any other query that depends on the session will return `null`. The UI for both the extension and the web app will be updated to show the user as logged out.
<Callout title="This will sign out the user from the web app as well" type="warn">
As web app is using the same session cookie, the user will be signed out from the web app as well. **This is intentional**, as your extension will most probably serves as an add-on for the web app and it doesn't make sense to keep the user signed in there if the extension is not used.
</Callout>
![Sign out](/images/docs/web/auth/sign-out.png)

68
.context/turbostarter-framework-context/sections/extension/billing.md Normal file
View File

@@ -0,0 +1,68 @@
---
title: Billing
description: Get started with billing in TurboStarter.
url: /docs/extension/billing
---
# Billing
As you could guess, there is no sense in implementing the whole billing process inside the browser extension, so we're relying on the [web app](/docs/web/billing/overview) to handle it.
> You probably won't display pricing tables inside a popup window, right?
You can customize the whole flow and onboarding process when a user purchases a plan in your [web app](/docs/web/billing/overview).
Then you would be able to easily fetch customer data to ensure that the user has access to correct extension features.
## Fetching customer data
When your user has purchased a plan from your landing page or web app, you can easily fetch their data using the [API](/docs/extension/api/client).
To do so, just invoke the `getCustomer` query on the `billing` router:
```tsx title="customer-screen.tsx"
import { api } from "~/lib/api";
export default function CustomerScreen() {
const { data: customer, isLoading } = useQuery({
queryKey: ["customer"],
queryFn: handle(api.billing.customer.$get),
});
if (isLoading) return <p>Loading...</p>;
return <p>{customer?.plan}</p>;
}
```
You may also want to ensure that user is logged in before fetching their billing data to avoid unnecessary API calls.
```tsx title="header.tsx"
import { api } from "~/lib/api";
import { authClient } from "~/lib/auth";
export const User = () => {
const {
data: { user },
} = authClient.useSession();
const { data: customer } = useQuery({
queryKey: ["customer"],
queryFn: handle(api.billing.customer.$get),
enabled: !!user, // [!code highlight]
});
if (!user || !customer) {
return null;
}
return (
<div>
<p>{user.email}</p>
<p>{customer.plan}</p>
</div>
);
};
```
Read more about [auth in extension](/docs/extension/auth/overview).

92
.context/turbostarter-framework-context/sections/extension/cli.md Normal file
View File

@@ -0,0 +1,92 @@
---
title: CLI
description: Start your new app project with a single command.
url: /docs/extension/cli
---
# CLI
<CliDemo />
To help you get started with TurboStarter **as quickly as possible**, we've developed a [CLI](https://www.npmjs.com/package/@turbostarter/cli) that enables you to create a new project (with all the configuration) in seconds.
The CLI is a set of commands that will help you create a new project, generate code, and manage your project efficiently.
Currently, the following action is available:
* **Starting a new project** - Generate starter code for your project with all necessary configurations in place (billing, database, emails, etc.)
**The CLI is in beta**, and we're actively working on adding more commands and actions. Soon, the following features will be available:
* **Translations** - Translate your project, verify translations, and manage them effectively
* **Installing plugins** - Easily install plugins for your project
* **Dynamic code generation** - Generate dynamic code based on your project structure
## Installation
You can run commands using `npx`:
```bash
npx turbostarter <command>
npx @turbostarter/cli@latest <command>
```
<Callout>
If you don't want to install the CLI globally, you can simply replace the examples below with `npx @turbostarter/cli@latest` instead of `turbostarter`.
This also allows you to always run the latest version of the CLI without having to update it.
</Callout>
## Usage
Running the CLI without any arguments will display the general information about the CLI:
```bash
Usage: turbostarter [options] [command]
Your Turbo Assistant for starting new projects, adding plugins and more.
Options:
-v, --version display the version number
-h, --help display help for command
Commands:
new create a new TurboStarter project
help [command] display help for command
```
You can also display help for it or check the actual version.
### Starting a new project
Use the `new` command to initialize configuration and dependencies for a new project.
```bash
npx turbostarter new
```
You will be asked a few questions to configure your project:
```bash
✔ All prerequisites are satisfied, let's start! 🚀
? What do you want to ship? ›
◉ Web app
◉ Mobile app
◯ Browser extension
? Enter your project name. ›
? How do you want to use database? ›
Local (powered by Docker)
Cloud
? What do you want to use for billing? ›
Stripe
Lemon Squeezy
...
🎉 You can now get started. Open the project and just ship it! 🎉
Problems? https://www.turbostarter.dev/docs
```
It will create a new project, configure providers, install dependencies and start required services in development mode.

63
.context/turbostarter-framework-context/sections/extension/configuration/app.md Normal file
View File

@@ -0,0 +1,63 @@
---
title: App configuration
description: Learn how to setup the overall settings of your extension.
url: /docs/extension/configuration/app
---
# App configuration
The application configuration is set at `apps/extension/src/config/app.ts`. This configuration stores some overall variables for your application.
This allows you to host multiple apps in the same monorepo, as every application defines its own configuration.
The recommendation is to **not update this directly** - instead, please define the environment variables and override the default behavior. The configuration is strongly typed so you can use it safely accross your codebase - it'll be validated at build time.
```ts title="apps/extension/src/config/app.ts"
import env from "env.config";
export const appConfig = {
name: env.VITE_PRODUCT_NAME,
url: env.VITE_SITE_URL,
locale: env.VITE_DEFAULT_LOCALE,
theme: {
mode: env.VITE_THEME_MODE,
color: env.VITE_THEME_COLOR,
},
} as const;
```
For example, to set the extension default theme color, you'd update the following variable:
```dotenv title=".env.local"
VITE_THEME_COLOR="yellow"
```
<Callout type="warn" title="Do NOT use process.env!">
Do NOT use `process.env` to get the values of the variables. Variables
accessed this way are not validated at build time, and thus the wrong variable
can be used in production.
</Callout>
## WXT config
To configure framework-specific settings, you can use the `wxt.config.ts` file. You can configure a lot of options there, such as [manifest](/docs/extension/configuration/manifest), [project structure](https://wxt.dev/guide/essentials/project-structure.html) or even [underlying Vite config](https://wxt.dev/guide/essentials/config/vite.html):
```ts title="wxt.config.ts"
import { defineConfig } from "wxt";
export default defineConfig({
srcDir: "src",
entrypointsDir: "app",
outDir: "build",
modules: [],
manifest: {
// Put manifest changes here
},
vite: () => ({
// Override config here, same as `defineConfig({ ... })`
// inside vite.config.ts files
}),
});
```
Make sure to setup it correctly, as it's the main source of config for your development, build and publishing process.

123
.context/turbostarter-framework-context/sections/extension/configuration/environment-variables.md Normal file
View File

@@ -0,0 +1,123 @@
---
title: Environment variables
description: Learn how to configure environment variables.
url: /docs/extension/configuration/environment-variables
---
# Environment variables
Environment variables are defined in the `.env` file in the root of the repository and in the root of the `apps/extension` package.
* **Shared environment variables**: Defined in the **root** `.env` file. These are shared between environments (e.g., development, staging, production) and apps (e.g., web, extension).
* **Environment-specific variables**: Defined in `.env.development` and `.env.production` files. These are specific to the development and production environments.
* **App-specific variables**: Defined in the app-specific directory (e.g., `apps/extension`). These are specific to the app and are not shared between apps.
* **Bundle-specific variables**: Specific to the [bundle target](https://wxt.dev/guide/essentials/config/environment-variables.html#built-in-environment-variables) (e.g. `.env.safari`, `.env.firefox`) or [bundle tag](https://wxt.dev/guide/essentials/config/environment-variables.html#built-in-environment-variables) (e.g. `.env.testing`)
* **Build environment variables**: Not stored in the `.env` file. Instead, they are stored in the environment variables of the CI/CD system.
* **Secret keys**: They're not stored on the extension side, instead [they're defined on the web side.](/docs/web/configuration/environment-variables#secret-keys)
## Shared variables
Here you can add all the environment variables that are shared across all the apps.
To override these variables in a specific environment, please add them to the specific environment file (e.g. `.env.development`, `.env.production`).
```dotenv title=".env.local"
# Shared environment variables
# The database URL is used to connect to your database.
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
# The name of the product. This is used in various places across the apps.
PRODUCT_NAME="TurboStarter"
# The url of the web app. Used mostly to link between apps.
URL="http://localhost:3000"
...
```
## App-specific variables
Here you can add all the environment variables that are specific to the app (e.g. `apps/extension`).
You can also override the shared variables defined in the root `.env` file.
```dotenv title="apps/extension/.env.local"
# App-specific environment variables
# Env variables extracted from shared to be exposed to the client in WXT (Vite) extension
VITE_SITE_URL="${URL}"
VITE_DEFAULT_LOCALE="${DEFAULT_LOCALE}"
# Theme mode and color
VITE_THEME_MODE="system"
VITE_THEME_COLOR="orange"
...
```
<Callout title="VITE_ prefix">
To make environment variables available in the browser extension code, you need to prefix them with `VITE_`. They will be injected to the code during the build process.
Only environment variables prefixed with `VITE_` will be injected.
[Read more about Vite environment variables.](https://vite.dev/guide/env-and-mode.html#env-files)
</Callout>
## Bundle-specific variables
WXT also provides environment variables specific to a certain [build target](https://wxt.dev/guide/essentials/config/environment-variables.html#built-in-environment-variables) or [build tag](https://wxt.dev/guide/essentials/config/environment-variables.html#built-in-environment-variables) when creating the final bundle. Given the following build command:
```json title="package.json"
"scripts": {
"build": "wxt build -b firefox --mode testing"
}
```
The following env files will be considered, ordered by priority:
* `.env.firefox`
* `.env.testing`
* `.env`
You shouldn't worry much about this, as TurboStarter comes with already configured build processes for all the major browsers.
## Build environment variables
To allow your extension to build properly on CI you need to define your environment variables on your CI/CD system (e.g. [Github Actions](https://docs.github.com/en/actions/learn-github-actions/environment-variables)).
TurboStarter comes with predefined Github Actions workflow used to build and submit your extension to the stores. It's located in `.github/workflows/publish-extension.yml` file.
To correctly set up the build environment variables, you need to define them under `env` section and then add them as a [secrets](http://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) to your repository.
```yaml title="publish-extension.yml"
...
jobs:
extension:
name: 🚀 Publish extension
runs-on: ubuntu-latest
environment: Production
env:
VITE_SITE_URL: ${{ secrets.SITE_URL }}
...
```
We'll go through the whole process of building and publishing the extension in the [publishing guide](/docs/extension/publishing/checklist).
## Secret keys
Secret keys and sensitive information are to be **never** stored on the extension app code.
<Callout title="What does this mean?">
It means that you will need to add the secret keys to the **web app, where the API is deployed.**
The browser extension should only communicate with the backend API, which is typically part of the web app. The web app is responsible for handling sensitive operations and storing secret keys securely.
[See web documentation for more details.](/docs/web/configuration/environment-variables#secret-keys)
This is not a TurboStarter-specific requirement, but a best practice for security for any
application. Ultimately, it's your choice.
</Callout>

111
.context/turbostarter-framework-context/sections/extension/configuration/manifest.md Normal file
View File

@@ -0,0 +1,111 @@
---
title: Manifest
description: Learn how to configure the manifest of your extension.
url: /docs/extension/configuration/manifest
---
# Manifest
As a requirement from web stores, every extension must have a `manifest.json` file in its root directory that lists important information about the structure and behavior of that extension.
It's a JSON file that contains metadata about the extension, such as its name, version, and permissions.
You can read more about it in the [official documentation](https://developer.chrome.com/docs/extensions/reference/manifest).
## Where is the `manifest.json` file?
WXT **abstracts away** the manifest file. The framework generates the manifest under the hood based on your source files and configurations you export from your code, similar to how Next.js abstracts page routing and SSG with the file system and page components.
That way, you don't have to manually create the `manifest.json` file and worry about correctly setting all the fields.
Most of the common properties are taken from the `package.json` and `wxt.config.ts` files:
| Manifest Field | Abstractions |
| ------------------------ | ------------------------------------------------------------- |
| icons | Auto generated with the `icon.png` in the `/assets` directory |
| action, browser\_actions | Popup window |
| options\_ui | Options page |
| content\_scripts | Content scripts |
| background | Background service worker |
| version | set by the `version` field in `package.json` |
| name | set by the `name` field in `wxt.config.ts` |
| description | set by the `description` field in `wxt.config.ts` |
| author | set by the `author` field in `wxt.config.ts` |
| homepage\_url | set by the `homepage` field in `wxt.config.ts` |
WXT build process centralizes common metadata and resolves any static file references (such as popup, background, content scripts, and so on) automatically.
This enables you to focus on the metadata that matters, such as name, description, OAuth, and so on.
## Overriding manifest
Sometimes, you want to override the default manifest fields (e.g. because you need to add a new permission that is required for your extension to work).
You'll need to modify your project's `wxt.config.ts` like so:
```ts title="apps/extension/wxt.config.ts"
export default defineConfig({
manifest: {
permissions: ["activeTab"],
},
});
```
Then, your settings will be merged with the settings auto-generated by WXT.
### Environment variables
You can use environment variables inside the manifest overrides:
```ts title="apps/extension/wxt.config.ts"
export default defineConfig({
manifest: {
browser_specific_settings: {
gecko: {
id: import.meta.env.VITE_FIREFOX_EXT_ID,
},
},
},
});
```
If the environment variable could not be found, the field will be removed completely from the manifest.
### Locales
TurboStarter extension supports [extension localization](https://developer.chrome.com/docs/extensions/reference/api/i18n) out-of-the-box. You can customize e.g. your extension's name and description based on the language of the user's browser.
Locales are defined in the `/public/_locales` directory. The directory should contain a `messages.json` file for each language you want to support (e.g. `/public/_locales/en/messages.json` and `/public/_locales/es/messages.json`).
By default, the first locale alphabetically available is used as default. However, you can specify a `default_locale` in your manifest like so:
```ts title="apps/extension/wxt.config.ts"
export default defineConfig({
manifest: {
default_locale: "en",
},
});
```
To reference a locale string inside your manifest overrides, wrap the key inside `__MSG_<key>__`:
```ts title="apps/extension/wxt.config.ts"
export default defineConfig({
manifest: {
name: "__MSG_extensionName__",
description: "__MSG_extensionDescription__",
},
});
```
Apart of this, we also configure [in-extension internationalization](/docs/extension/internationalization) out-of-the-box to easily translate your components and views.
<Cards>
<Card title="Manifest file format" href="https://developer.chrome.com/docs/extensions/reference/manifest" description="developer.chrome.com" />
<Card title="WXT Manifest" href="https://wxt.dev/guide/essentials/config/manifest.html" description="wxt.dev" />
<Card title="chrome.i18n" href="https://developer.chrome.com/docs/extensions/reference/api/i18n" description="developer.chrome.com" />
<Card title="WXT i18n" href="https://wxt.dev/guide/essentials/i18n.html" description="wxt.dev" />
</Cards>

83
.context/turbostarter-framework-context/sections/extension/customization/add-app.md Normal file
View File

@@ -0,0 +1,83 @@
---
title: Adding apps
description: Learn how to add apps to your Turborepo workspace.
url: /docs/extension/customization/add-app
---
# Adding apps
<Callout title="Advanced topic" type="warn">
This is an **advanced topic** - you should only follow these instructions if you are sure you want to add a new app to your TurboStarter project within your monorepo and want to keep pulling updates from the TurboStarter repository.
</Callout>
In some ways - creating a new repository may be the easiest way to manage your application. However, if you want to keep your application within the monorepo and pull updates from the TurboStarter repository, you can follow these instructions.
To pull updates into a separate application outside of `extension` - we can use [git subtree](https://www.atlassian.com/git/tutorials/git-subtree).
Basically, we will create a subtree at `apps/extension` and create a new remote branch for the subtree. When we create a new application, we will pull the subtree into the new application. This allows us to keep it in sync with the `apps/extension` folder.
To add a new app to your TurboStarter project, you need to follow these steps:
<Steps>
<Step>
## Create a subtree
First, we need to create a subtree for the `apps/extension` folder. We will create a branch named `extension-branch` and create a subtree for the `apps/extension` folder.
```bash
git subtree split --prefix=apps/extension --branch extension-branch
```
</Step>
<Step>
## Create a new app
Now, we can create a new application in the `apps` folder.
Let's say we want to create a new app `ai-chat` at `apps/ai-chat` with the same structure as the `apps/extension` folder (which acts as the template for all new apps).
```bash
git subtree add --prefix=apps/ai-chat origin extension-branch --squash
```
You should now be able to see the `apps/ai-chat` folder with the contents of the `apps/extension` folder.
</Step>
<Step>
## Update the app
When you want to update the new application, follow these steps:
### Pull the latest updates from the TurboStarter repository
The command below will update all the changes from the TurboStarter repository:
```bash
git pull upstream main
```
### Push the `extension-branch` updates
After you have pulled the updates from the TurboStarter repository, you can split the branch again and push the updates to the extension-branch:
```bash
git subtree split --prefix=apps/extension --branch extension-branch
```
Now, you can push the updates to the `extension-branch`:
```bash
git push origin extension-branch
```
### Pull the updates to the new application
Now, you can pull the updates to the new application:
```bash
git subtree pull --prefix=apps/ai-chat origin extension-branch --squash
```
</Step>
</Steps>
That's it! You now have a new application in the monorepo 🎉

100
.context/turbostarter-framework-context/sections/extension/customization/add-package.md Normal file
View File

@@ -0,0 +1,100 @@
---
title: Adding packages
description: Learn how to add packages to your Turborepo workspace.
url: /docs/extension/customization/add-package
---
# Adding packages
<Callout title="Advanced topic" type="warn">
This is an **advanced topic** - you should only follow these instructions if you are sure you want to add a new package to your TurboStarter application instead of adding a folder to your application in `apps/web` or modify existing packages under `packages`. You don't need to do this to add a new page or component to your application.
</Callout>
To add a new package to your TurboStarter application, you need to follow these steps:
<Steps>
<Step>
## Generate a new package
First, enter the command below to create a new package in your TurboStarter application:
```bash
turbo gen package
```
Turborepo will ask you to enter the name of the package you want to create. Enter the name of the package you want to create and press enter.
If you don't want to add dependencies to your package, you can skip this step by pressing enter.
The command will have generated a new package under packages named `@turbostarter/<package-name>`. If you named it `example`, the package will be named `@turbostarter/example`.
</Step>
<Step>
## Export a module from your package
By default, the package exports a single module using the `index.ts` file. You can add more exports by creating new files in the package directory and exporting them from the `index.ts` file or creating export files in the package directory and adding them to the `exports` field in the `package.json` file.
### From `index.ts` file
The easiest way to export a module from a package is to create a new file in the package directory and export it from the `index.ts` file.
```ts title="packages/example/src/module.ts"
export function example() {
return "example";
}
```
Then, export the module from the `index.ts` file.
```ts title="packages/example/src/index.ts"
export * from "./module";
```
### From `exports` field in `package.json`
**This can be very useful for tree-shaking.** Assuming you have a file named `module.ts` in the package directory, you can export it by adding it to the `exports` field in the `package.json` file.
```json title="packages/example/package.json"
{
"exports": {
".": "./src/index.ts",
"./module": "./src/module.ts"
}
}
```
**When to do this?**
1. when exporting two modules that don't share dependencies to ensure better tree-shaking. For example, if your exports contains both client and server modules.
2. for better organization of your package
For example, create two exports `client` and `server` in the package directory and add them to the `exports` field in the `package.json` file.
```json title="packages/example/package.json"
{
"exports": {
".": "./src/index.ts",
"./client": "./src/client.ts",
"./server": "./src/server.ts"
}
}
```
1. The `client` module can be imported using `import { client } from '@turbostarter/example/client'`
2. The `server` module can be imported using `import { server } from '@turbostarter/example/server'`
</Step>
<Step>
## Use the package in your extension
You can now use the package in your extension by importing it using the package name:
```ts title="app/popup/index.tsx"
import { example } from "@turbostarter/example";
console.log(example());
```
</Step>
</Steps>
Et voilà! You have successfully added a new package to your TurboStarter extension. 🎉

120
.context/turbostarter-framework-context/sections/extension/customization/components.md Normal file
View File

@@ -0,0 +1,120 @@
---
title: Components
description: Manage and customize your extension components.
url: /docs/extension/customization/components
---
# Components
For the components part, we're using [shadcn/ui](https://ui.shadcn.com) for atomic, accessible and highly customizable components.
<Callout type="info" title="Why shadcn/ui?">
shadcn/ui is a powerful tool that allows you to generate pre-designed
components with a single command. It's built with Tailwind CSS and Radix UI,
and it's highly customizable.
</Callout>
TurboStarter defines two packages that are responsible for the UI part of your app:
* `@turbostarter/ui` - shared styles, [themes](/docs/web/customization/styling#themes) and assets (e.g. icons)
* `@turbostarter/ui-web` - pre-built UI web components, ready to use in your app
## Adding a new component
There are basically two ways to add a new component:
<Tabs items={["Using the CLI", "Copy-pasting"]}>
<Tab value="Using the CLI">
TurboStarter is fully compatible with [shadcn CLI](https://ui.shadcn.com/docs/cli), so you can generate new components with single command.
Run the following command from the **root** of your project:
```bash
pnpm --filter @turbostarter/ui-web ui:add
```
This will launch an interactive command-line interface to guide you through the process of adding a new component where you can pick which component you want to add.
```bash
Which components would you like to add? > Space to select. A to toggle all.
Enter to submit.
◯ accordion
◯ alert
◯ alert-dialog
◯ aspect-ratio
◯ avatar
◯ badge
◯ button
◯ calendar
◯ card
◯ checkbox
```
Newly created components will appear in the `packages/ui/web/src` directory.
</Tab>
<Tab value="Copy-pasting">
You can always copy-paste a component from the [shadcn/ui](https://ui.shadcn.com/docs/components) website and modify it to your needs.
This is possible, because the components are headless and don't need (in most cases) any additional dependencies.
Copy code from the website, create a new file in the `packages/ui/web/src` directory and paste the code into the file.
</Tab>
</Tabs>
<Callout title="Keep it atomic" type="warn">
Keep in mind that you should always try to keep shared components as atomic as possible. This will make it easier to reuse them and to build specific views by composition.
E.g. include components like `Button`, `Input`, `Card`, `Dialog` in shared package, but keep specific components like `LoginForm` in your app directory.
</Callout>
## Using components
Each component is a standalone entity which has a separate export from the package. It helps to keep things modular, avoid unnecessary dependencies and make tree-shaking possible.
To import a component from the UI package, use the following syntax:
```tsx title="components/my-component.tsx"
// [!code word:card]
import {
Card,
CardContent,
CardHeader,
CardFooter,
CardTitle,
CardDescription,
} from "@turbostarter/ui-web/card";
```
Then you can use it to build a component specific to your app:
```tsx title="components/my-component.tsx"
export function MyComponent() {
return (
<Card>
<CardHeader>
<CardTitle>My Component</CardTitle>
</CardHeader>
<CardContent>
<p>My Component Content</p>
</CardContent>
<CardFooter>
<Button>Click me</Button>
</CardFooter>
</Card>
);
}
```
<Callout title="Recommendation: use v0 to generate layouts">
We recommend using [v0](https://v0.dev) to generate layouts for your app. It's a powerful tool that allows you to generate layouts from the natural language instructions.
Of course, **it won't replace a designer**, but it can be a good starting point for your layout.
</Callout>
<Cards>
<Card href="https://ui.shadcn.com/" title="shadcn/ui" description="ui.shadcn.com" />
<Card href="https://v0.dev/chat" title="v0 by Vercel" description="v0.dev" />
</Cards>

159
.context/turbostarter-framework-context/sections/extension/customization/styling.md Normal file
View File

@@ -0,0 +1,159 @@
---
title: Styling
description: Get started with styling your extension.
url: /docs/extension/customization/styling
---
# Styling
To build the extension interface TurboStarter comes with [Tailwind CSS](https://tailwindcss.com/) and [Radix UI](https://www.radix-ui.com/) pre-configured.
<Callout title="Why Tailwind CSS and Radix UI?" type="info">
The combination of Tailwind CSS and Radix UI gives ready-to-use, accessible UI components that can be fully customized to match your brands design.
</Callout>
## Tailwind configuration
In the `packages/ui/shared/src/styles` directory, you will find shared CSS files with Tailwind CSS configuration. To change global styles, you can edit the files in this folder.
Here is an example of a shared CSS file that includes the Tailwind CSS configuration:
```css title="packages/ui/shared/src/styles/globals.css"
@import "tailwindcss";
@import "./themes.css";
@custom-variant dark (&:is(.dark *));
:root {
--radius: 0.65rem;
}
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-popover: var(--popover);
--color-popover-foreground: var(--popover-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
...
}
```
For colors, we rely strictly on [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) in [OKLCH](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) format to allow for easy theme management without the need for any JavaScript.
Also, each app has its own `globals.css` file, which extends the shared config and allows you to override the global styles.
Here is an example of an extension's `globals.css` file:
```css title="apps/extension/src/assets/styles/globals.css"
@import url("https://fonts.googleapis.com/css2?family=Geist+Mono:wght@100..900&family=Geist:wght@100..900&display=swap");
@import "@turbostarter/ui/globals.css";
@import "@turbostarter/ui-web/globals.css";
@theme {
--font-sans: "Geist", sans-serif;
--font-mono: "Geist Mono", monospace;
}
```
This way, we maintain a separation of concerns and a clear structure for the Tailwind CSS configuration.
## Themes
TurboStarter comes with **9+** predefined themes, which you can use to quickly change the look and feel of your app.
They're defined in the `packages/ui/shared/src/styles/themes` directory. Each theme is a set of variables that can be overridden:
```ts title="packages/ui/shared/src/styles/themes/colors/orange.ts"
export const orange = {
light: {
background: [1, 0, 0],
foreground: [0.141, 0.005, 285.823],
card: [1, 0, 0],
"card-foreground": [0.141, 0.005, 285.823],
...
}
} satisfies ThemeColors;
```
Each variable is stored as a [OKLCH](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) array, which is then converted to a CSS variable at build time (by our custom build script). That way we can ensure full type-safety and reuse themes across different parts of our apps (e.g. use the same theme in emails).
Feel free to add your own themes or override the existing ones to match your brand's identity.
To apply a theme to your app, you can use the `data-theme` attribute on your layout wrapper for each part of the extension:
```tsx title="modules/common/layout/layout.tsx"
import { StorageKey, useStorage } from "~/lib/storage";
export const Layout = ({ children }: { children: React.ReactNode }) => {
const { data } = useStorage(StorageKey.THEME);
return (
<div id="main" data-theme={data.color}>
{children}
</div>
);
};
```
In TurboStarter, we're using [Storage API](/docs/extension/structure/storage) to persist the user's theme selection and then apply it to the `div#main` element.
## Dark mode
The starter kit comes with a built-in dark mode support.
Each theme has a corresponding dark mode variables which are used to change the theme to its dark mode counterpart.
```ts title="packages/ui/shared/src/styles/themes/colors/orange.ts"
export const orange = {
light: {},
dark: {
background: [0.141, 0.005, 285.823],
foreground: [0.985, 0, 0],
card: [0.21, 0.006, 285.885],
"card-foreground": [0.985, 0, 0],
...
}
} satisfies ThemeColors;
```
Because the dark variant is defined to use a class (`@custom-variant dark (&:is(.dark *))`) in the shared Tailwind configuration, we need to add the `dark` class to the root element to apply dark mode styles.
The same as for the theme color, we're using here the [Storage API](/docs/extension/structure/storage) to persist the user's dark mode selection and then apply correct class name to the root `div` element:
```tsx title="modules/common/layout/layout.tsx"
import { StorageKey, useStorage } from "~/lib/storage";
export const Layout = ({ children }: { children: React.ReactNode }) => {
const { data } = useStorage(StorageKey.THEME);
return (
<div
id="root"
className={cn({
dark:
data.mode === THEME_MODE.DARK ||
(data.mode === THEME_MODE.SYSTEM &&
window.matchMedia("(prefers-color-scheme: dark)").matches),
})}
>
{children}
</div>
);
};
```
You can also define the default theme mode and color in the [app configuration](/docs/extension/configuration/app).
<Cards>
<Card title="Tailwind CSS" description="tailwindcss.com" href="https://tailwindcss.com/" />
<Card title="Radix UI" description="radix-ui.com" href="https://www.radix-ui.com/" />
</Cards>

39
.context/turbostarter-framework-context/sections/extension/database.md Normal file
View File

@@ -0,0 +1,39 @@
---
title: Database
description: Get started with the database.
url: /docs/extension/database
---
# Database
<Callout type="error" title="API deployment required">
To enable communication between your WXT extension and the server in a production environment, the web application with Hono API must be deployed first.
<Cards>
<Card title="API" description="Learn more about the API." href="/docs/web/api/overview" />
<Card title="Web deployment" description="Deploy your web application to production." href="/docs/web/deployment/checklist" />
</Cards>
</Callout>
As browser extensions use only client-side code, **there's no way to interact with the database directly**.
Also, you should avoid any workarounds to interact with the database directly, because it can lead to leaking your database credentials and other security issues.
## Recommended approach
You can safely use the [API](/docs/extension/api/overview) and invoke procedures which will run queries on the database.
To do this you need to set up the database on the [web, server side](/docs/web/database/overview) and then use the [API client](/docs/extension/api/client) to interact with it.
Learn more about its configuration in the web part of the docs, especially in the following sections:
<Cards>
<Card title="Overview" description="Get started with the database" href="/docs/web/database/overview" />
<Card title="Schema" description="Learn about the database schema." href="/docs/web/database/schema" />
<Card title="Migrations" description="Migrate your changes to the database." href="/docs/web/database/migrations" />
<Card title="Database client" description="Use database client to interact with the database." href="/docs/web/database/client" />
</Cards>

66
.context/turbostarter-framework-context/sections/extension/extras.md Normal file
View File

@@ -0,0 +1,66 @@
---
title: Extras
description: See what you get together with the code.
url: /docs/extension/extras
---
# Extras
## Tips and Tricks
In many places, next to the code you will find some marketing tips, design suggestions, and potential risks. This is to help you build a better product and avoid common pitfalls.
```tsx title="Hero.tsx"
return (
<header>
{/* 💡 Use something that user can visualize e.g.
"Ship your startup while on the toilet" */}
<h1>Best startup on the world</h1>
</header>
);
```
### Submission tips
When it comes to mobile app and browser extension, you must submit your product to review from Apple/Google etc. We have some tips for you to make sure your submission goes smoothly.
```json title="app.json"
{
"ios": {
"infoPlist": {
/* 🍎 add descriptive justification of using this permission on iOS */
"NSCameraUsageDescription": "This app uses the camera to scan barcodes on event tickets."
}
}
}
```
As well as providing you with the info on how to make your store listings better:
```json title="package.json"
{
"manifest": {
/* 💡 Use localized messages to get more visibility in web stores */
"name": "__MSG_extensionName__",
"default_locale": "en"
}
}
```
## Discord community
We have a Discord community where you can ask questions and share your projects. It's a great place to get help and meet other developers. Check more details at [/discord](/discord).
<DiscordCta source="extras" />
![Discord](/images/docs/discord.png)
## 25+ SaaS Ideas
Not sure what to build? We have a list of **25+** SaaS ideas that you can use to get started 🔥
Grouped by category, these ideas are a great way to get inspired and start building your next project.
Including design, copies, marketing tips and potential risks, this list is a great resource for anyone looking to build a SaaS product.
![SaaS Ideas](/images/docs/saas-ideas.png)

92
.context/turbostarter-framework-context/sections/extension/faq.md Normal file
View File

@@ -0,0 +1,92 @@
---
title: FAQ
description: Find answers to common technical questions.
url: /docs/extension/faq
---
# FAQ
## Why isn't everything hidden and configured with one BIG config file?
TurboStarter intentionally exposes the underlying code rather than hiding it behind configuration files (like some starters do). This design choice follows our **you own your code** philosophy, giving you full control and flexibility over your codebase.
While a single config file might seem simpler initially, it often becomes restrictive when you need to customize functionality beyond what the config allows. With direct access to the code, you can modify any part of the system to match your specific requirements.
## I don't know some technology! Should I buy TurboStarter?
You should be prepared for a learning curve or consider learning it first. However, TurboStarter will still work for you if you're willing to learn.
Even without knowing some technologies, you can still use the rest of the features.
## I don't need mobile app or browser extension, what should I do?
You can simply ignore the mobile app and browser extension parts of the project. You can remove the `apps/mobile` and `apps/extension` directories from the project.
The modular nature of TurboStarter allows you to remove parts of the project that you don't need without affecting the rest of the stack.
## I want to use a different provider for X
Sure! TurboStarter is designed to be modular, so configuring new provider (e.g. for emails, billing or any other service) is straightforward. You just need to make sure your configuration is compatible with common interface to be able to plug it into the codebase.
## Will you add more packages in the future?
Yes, we will keep updating TurboStarter with new packages and features. This kit is designed to be modular, allowing for new features and packages to be added without interfering with your existing code. You can always [update your project](/docs/web/installation/update) to the latest version.
## Can I use this kit for a non-SaaS project?
This kit is mainly designed for SaaS projects. If you're building something other than a SaaS, the Next.js SaaS Boilerplate might include features you don't need. You can still use it for non-SaaS projects, but you may need to remove or modify features that are specific to SaaS use cases.
## Can I use personal accounts only?
Yes! You can disable team accounts and have personal accounts only by setting a feature flag.
## Does it set up the production instance for me?
No, TurboStarter does not set up the production instance for you. This includes setting up databases, Stripe, or any other services you need. TurboStarter does not have access to your Stripe or Resend accounts, so setup on your end is required. TurboStarter provides the codebase and documentation to help you set up your SaaS project.
## Does the starter include Solito?
No. Solito will not be included in this repo. It is a great tool if you want to share code between your Next.js and Expo app. However, the main purpose of this repo is not the integration between Next.js and Expo — it's the code splitting of your SaaS platforms into a monorepo. You can utilize the monorepo with multiple apps, and it can be any app such as Vite, Electron, etc.
Integrating Solito into this repo isn't hard, and there are a few [official templates](https://github.com/nandorojo/solito/tree/master/example-monorepos) by the creators of Solito that you can use as a reference.
## Does this pattern leak backend code to my client applications?
No, it does not. The `api` package should only be a production dependency in the Next.js application where it's served. The Expo app, browser extension, and all other apps you may add in the future should only add the `api` package as a dev dependency. This lets you have full type safety in your client applications while keeping your backend code safe.
If you need to share runtime code between the client and server, you can create a separate `shared` package for this and import it on both sides.
## How do I get support if I encounter issues?
For support, you can:
1. Visit our [Discord](https://discord.gg/KjpK2uk3JP)
2. Contact us via support email ([hello@turbostarter.dev](mailto:hello@turbostarter.dev))
## Are there any example projects or demos?
Yes - feel free to check out our demo app at [demo.turbostarter.dev](https://demo.turbostarter.dev). Also, you can get inspired by projects built by our customers - take a look at [Showcase](/#showcase).
## How do I deploy my application?
Please check the [production checklist](/docs/web/deployment/checklist) for more information.
## How do I update my project when a new version of the boilerplate is released?
Please read the [documentation for updating your TurboStarter code](/docs/web/installation/update).
## Can I use the React package X with this kit?
Yes, you can use any React package with this kit. The kit is based on React, so you are generally only constrained by the underlying technologies and not by the kit itself. Since you own and can edit all the code, you can adapt the kit to your needs. However, if there are limitations with the underlying technology, you might need to work around them.
## Can I integrate TurboStarter into an existing project?
TurboStarter is a full-stack starter intended to be used as the foundation of your app. You can copy individual modules or patterns into an existing codebase, but retrofitting the entire starter into a mature project is typically not recommended and is not officially supported. If you choose to copy parts, prefer isolating boundaries (e.g., `packages/` modules) and aligning interfaces first.
## Where can I deploy my application?
TurboStarter targets modern Node.js/Next.js runtimes. You can deploy to providers that support these environments, such as [Vercel](/docs/web/deployment/vercel), [Railway](/docs/web/deployment/railway), [Render](/docs/web/deployment/render), [Fly](/docs/web/deployment/fly), or [Netlify](/docs/web/deployment/netlify) - following their Next.js guidance. Review our [production checklist](/docs/web/deployment/checklist) before going live.
## Can I easily swap providers (billing, email, etc.)?
Yes. The starter organizes integrations behind clear interfaces so you can replace providers (e.g., billing or email) with minimal surface changes. Keep your implementation behind a module boundary and adapt to the existing types to avoid ripple effects.

336
.context/turbostarter-framework-context/sections/extension/index.md Normal file
View File

@@ -0,0 +1,336 @@
---
title: Introduction
description: Get started with TurboStarter extension kit.
url: /docs/extension
---
# Introduction
Welcome to the TurboStarter documentation. This is your starting point for learning about the starter kit, its structure, features, and how to use it for your app development.
<ThemedImage light="/images/docs/demo/light.webp" dark="/images/docs/demo/dark.webp" alt="TurboStarter demo" width={2311} height={1562} zoomable priority />
## What is TurboStarter?
TurboStarter is a fullstack starter kit that helps you build scalable and production-ready web apps, mobile apps, and browser extensions in minutes.
Looking to bootstrap your project quickly? Check out our [TurboStarter CLI guide](/blog/the-only-turbo-cli-you-need-to-start-your-next-project-in-seconds) to get started in seconds.
## Demo apps
TurboStarter provides a suite of live demo applications you can try instantly - right in your browser, on your phone, or via browser extensions. Try them live by clicking the buttons below.
<DemoBadges
urls={{
android:
"https://play.google.com/store/apps/details?id=com.turbostarter.core",
ios: "https://apps.apple.com/app/id6754278899",
chrome:
"https://chromewebstore.google.com/detail/bcjmonmlfbnngpkllpnpmnjajaciaboo",
firefox: "https://addons.mozilla.org/addon/turbostarter_",
edge: "https://microsoftedge.microsoft.com/addons/detail/turbostarter/ianbflanmmoeleokihabnmmcahhfijig",
web: "https://demo.turbostarter.dev",
}}
/>
## Principles
TurboStarter is built with the following principles:
* **As simple as possible** - It should be easy to understand, easy to use, and strongly avoid overengineering things.
* **As few dependencies as possible** - It should have as few dependencies as possible to allow you to take full control over every part of the project.
* **As performant as possible** - It should be fast and light without any unnecessary overhead.
## Features
Before diving into the technical details, let's overview the features TurboStarter provides.
### Multi-platform development
* [Web](/docs/web/stack): Build web apps with React, Next.js, and Tailwind CSS.
* [Mobile](/docs/mobile/stack): Build mobile apps with React Native and Expo.
* [Browser extension](/docs/extension/stack): Build browser extensions with React and WXT.
For those interested in AI development, check out our dedicated [TurboStarter AI documentation](/ai/docs) with specialized features for building AI-powered applications.
<Callout title="Available. Everywhere.">
Most features are available on all platforms. You can use the **same codebase** to build web, mobile, and browser extension apps.
</Callout>
### Authentication
<Cards>
<Card title="Ready-to-use components and views" description="Pre-built authentication components and pages that match your brand's unique style." className="shadow-none" />
<Card title="Email/password authentication" description="Traditional email and password auth implementing validation and security best practices." className="shadow-none" />
<Card title="Magic links" description="Passwordless authentication through secure email-based magic links, including rate limiting." className="shadow-none" />
<Card title="Password recovery" description="Complete password reset flow including email verification and secure token handling." className="shadow-none" />
<Card title="Multi-factor authentication (MFA)" description="Increase account security with support for 2FA (authenticator apps, TOTP), ready to use and customizable in your app." className="shadow-none" />
<Card title="Passkeys (passwordless)" description="Passwordless authentication using Passkeys (FIDO2/WebAuthn) for seamless, phishing-resistant sign-ins." className="shadow-none" />
<Card title="Anonymous" description="Allow users to proceed anonymously without requiring authentication." className="shadow-none" />
<Card title="OAuth providers" description="Pre-configured social authentication for Google and GitHub, ready to use." className="shadow-none" />
</Cards>
### Organizations/teams
<Cards>
<Card title="Multi-tenancy" description="Multi-tenant organization model with ownership and membership." className="shadow-none" />
<Card title="Teams and members" description="Create teams, invite members, assign roles and manage seats." className="shadow-none" />
<Card title="Invitations" description="Email-based invites with role presets and expiry." className="shadow-none" />
<Card title="Roles per organization" description="Role-based permissions scoped to each organization." className="shadow-none" />
</Cards>
### Billing
<Cards>
<Card title="Subscriptions" description="Recurring billing system supporting multiple plans, pricing tiers and usage metrics." className="shadow-none" />
<Card title="One-time payments" description="Simple payment processing featuring secure checkout and payment confirmation." className="shadow-none" />
<Card title="Webhooks" description="Real-time billing event handling and payment provider data synchronization." className="shadow-none" />
<Card title="Custom plans" description="Create and manage custom pricing plans offering flexible billing options." className="shadow-none" />
<Card title="Billing components" description="Ready-made components for pricing, checkout and billing management." className="shadow-none" />
<Card title="Multiple providers" description="Seamless integration of Stripe, LemonSqueezy and Polar payment systems." className="shadow-none" />
</Cards>
### Database
<Cards>
<Card title="Advanced querying" description="Type-safe SQL queries, relational joins, filters, ordering, pagination and more." className="shadow-none" />
<Card title="Schema migrations" description="Automated schema migrations with version control, rollback, and auto-generation." className="shadow-none" />
<Card title="Connection pooling" description="Standalone or serverless database connections with optimal pooling strategies." className="shadow-none" />
<Card title="Data validation" description="End-to-end data validation using shared types and schema definitions." className="shadow-none" />
</Cards>
### API
<Cards>
<Card title="Serverless architecture" description="Modern serverless infrastructure offering auto-scaling and high availability." className="shadow-none" />
<Card title="Single source of truth" description="Unified data management across all apps through shared types and validation." className="shadow-none" />
<Card title="Protected routes" description="Secure API endpoints implementing role-based access control and rate limiting." className="shadow-none" />
<Card title="Feature-based access" description="Access control based on features and subscription plans." className="shadow-none" />
<Card title="Typesafe client" description="Fully typesafe frontend client featuring automatic type generation." className="shadow-none" />
</Cards>
### Admin
<Cards>
<Card title="Super admin UI" description="Centralized admin workspace with overview metrics and quick actions." className="shadow-none" />
<Card title="User management" description="Search, filter and manage users, status, auth methods and MFA." className="shadow-none" />
<Card title="Roles and permissions" description="Granular access control for admins, moderators and support staff." className="shadow-none" />
<Card title="Impersonation" description="Securely impersonate users to reproduce issues and provide support." className="shadow-none" />
</Cards>
### AI
<Cards>
<Card title="Multiple providers" className="shadow-none">
Seamless integration of OpenAI, Anthropic, Groq, Mistral, and Gemini. For more advanced AI features, check out [TurboStarter AI](/ai/docs).
</Card>
<Card title="Ready-to-use components" description="Pre-built chatbot and assistant components supporting real-time streaming." className="shadow-none" />
<Card title="Streaming responses" description="Real-time AI response delivery including progress indicators." className="shadow-none" />
<Card title="Custom rules" description="Includes custom rules and prompts for AI editors and models to make you ship faster." className="shadow-none" />
</Cards>
### Internationalization
<Cards>
<Card title="Locale routing" description="Smart routing based on user locale and automatic language detection." className="shadow-none" />
<Card title="Multiple languages" description="Comprehensive multi-language support and translation management." className="shadow-none" />
<Card title="Language switching" description="One-click language changes and persistent preferences." className="shadow-none" />
<Card title="Mail templates" description="Multi-language email templates including fallback options." className="shadow-none" />
</Cards>
### Emails
<Cards>
<Card title="Transactional emails" description="Automated email delivery including tracking and analytics capabilities." className="shadow-none" />
<Card title="Marketing emails" description="Create and send marketing campaigns using beautiful templates." className="shadow-none" />
<Card title="Email templates" description="Responsive email templates supporting dark mode customization." className="shadow-none" />
<Card title="Multiple providers" description="Easy integration of SendGrid, Resend, and Nodemailer services." className="shadow-none" />
</Cards>
### Landing page
<Cards>
<Card title="Hero section" description="Dynamic hero with subtle animations, platform links, and primary/secondary CTAs." className="shadow-none" />
<Card title="Feature highlights" description="Grid and list layouts to present key features and differentiators." className="shadow-none" />
<Card title="Pricing plans" description="Billing-integrated pricing table with intervals, discounts and footer notes." className="shadow-none" />
<Card title="Testimonials" description="Social proof section with avatars, star ratings and counts." className="shadow-none" />
<Card title="FAQ" description="Structured FAQ with SEO schema for rich results." className="shadow-none" />
<Card title="Re-usable CTAs" description="Buttons, badges and links to docs, pricing and community." className="shadow-none" />
</Cards>
### Marketing
<Cards>
<Card title="SEO" description="Complete SEO toolkit including automatic sitemap generation." className="shadow-none" />
<Card title="Meta tags" description="Flexible meta tag system supporting social media previews." className="shadow-none" />
<Card title="Tips and tricks" description="Comprehensive tips and tricks for optimizing marketing of your app." className="shadow-none" />
<Card title="Mobile onboarding" description="Onboarding flow for mobile apps including custom steps, authentication, and more." className="shadow-none" />
<Card title="Blog" description="Full-featured blog system including categories and RSS feed." className="shadow-none" />
<Card title="Legal pages" description="Pre-built legal templates including version control." className="shadow-none" />
<Card title="Contact form" description="Smart contact form featuring spam protection and auto-responses." className="shadow-none" />
</Cards>
### Storage
<Cards>
<Card title="File uploads" description="Complete file upload system including progress tracking and validation." className="shadow-none" />
<Card title="S3 storage" description="S3-compatible storage offering automatic file optimization." className="shadow-none" />
</Cards>
### CMS
<Cards>
<Card title="Blog pages" description="Complete blog management system including categories and tags." className="shadow-none" />
<Card title="MDX content collections" description="Organized content structure using MDX-based collections and custom frontmatter." className="shadow-none" />
</Cards>
### Theming
<Cards>
<Card title="Built-in themes" description="10+ pre-built themes offering customizable color schemes." className="shadow-none" />
<Card title="Dark mode" description="Built-in dark mode supporting system preference detection." className="shadow-none" />
<Card title="Components CLI" description="Component generation tools following best practices and TypeScript standards." className="shadow-none" />
<Card title="Design system" description="Complete atomic design system including accessibility features." className="shadow-none" />
</Cards>
### Analytics
<Cards>
<Card title="Event tracking" description="Custom event tracking plus automatic session management." className="shadow-none" />
<Card title="Page views" description="Automatic page view capture including bounce rate metrics." className="shadow-none" />
<Card title="User identification" description="Cross-device user tracking and session management." className="shadow-none" />
<Card title="Multiple providers" description="Seamless integration with multiple platforms (e.g. Google Analytics, PostHog, Plausible, Umami, Open Panel, Vemetric)." className="shadow-none" />
</Cards>
### Monitoring
<Cards>
<Card title="Auto-capture exceptions" description="Automatically capture exceptions and errors in your application." className="shadow-none" />
<Card title="Track performance metrics" description="Track performance metrics such as page views, user sessions, and more." className="shadow-none" />
<Card title="Source maps" description="Automatically generate source maps for your application to improve error reporting." className="shadow-none" />
<Card title="Multiple providers" description="Seamless integration with multiple platforms (e.g. Sentry, PostHog)." className="shadow-none" />
</Cards>
### Deployment
<Cards>
<Card title="One-click deploy" description="Simple deployment to your preferred cloud provider." className="shadow-none" />
<Card title="Submission guide" description="Comprehensive guide for app store submissions and requirements." className="shadow-none" />
<Card title="CI/CD workflows" description="Pre-configured deployment pipelines including automated testing." className="shadow-none" />
<Card title="Over-the-air updates" description="Instantly push code or config updates to users without resubmitting to the app store." className="shadow-none" />
</Cards>
### Testing
<Cards>
<Card title="Unit tests" description="Write and run fast unit tests for individual functions and components with instant feedback." className="shadow-none" />
<Card title="Code coverage" description="See precise coverage metrics that show what code is and isn't tested, giving you valuable insight to improve your test suite." className="shadow-none" />
<Card title="Integration tests" description="Test the interaction between different modules or services to ensure everything works together as intended." className="shadow-none" />
<Card title="E2E tests" description="Simulate real user scenarios across the entire stack with automated end-to-end test tools and examples." className="shadow-none" />
</Cards>
## Use like LEGO blocks
The biggest advantage of TurboStarter is its modularity. You can use the entire stack or just the parts you need. It's like LEGO blocks - you can build anything you want with it.
If you don't need a specific feature, feel free to remove it without affecting the rest of the stack.
This approach allows for:
* **Easy feature integration** - plug new features into the kit with minimal changes.
* **Simplified maintenance** - keep the codebase clean and maintainable.
* **Core feature separation** - distinguish between core features and custom features.
* **Additional modules** - easily add modules like billing, CMS, monitoring, logger, mailer, and more.
## Scope of this documentation
While building a SaaS application involves many moving parts, this documentation focuses specifically on TurboStarter. For in-depth information on the underlying technologies, please refer to their respective official documentation.
This documentation will guide you through configuring, running, and deploying the kit, and will provide helpful links to the official documentation of technologies where necessary.
## `llms.txt`
You can access the entire TurboStarter documentation in Markdown format at [/llms.txt](/llms.txt). This can be used to ask any LLM (assuming it has a big enough context window) questions about the TurboStarter based on the most up-to-date documentation.
### Example usage
For instance, to prompt an LLM with questions about the TurboStarter:
1. Copy the documentation contents from [/llms.txt](/llms.txt)
2. Use the following prompt format:
```
Documentation:
{paste documentation here}
---
Based on the above documentation, answer the following:
{your question}
```
## Enjoy!
This documentation is designed to be easy to follow and understand. If you have any questions or need help, feel free to reach out to us at [hello@turbostarter.dev](mailto:hello@turbostarter.dev).
Explore new features, build amazing apps, and have fun! 🚀

65
.context/turbostarter-framework-context/sections/extension/installation/clone.md Normal file
View File

@@ -0,0 +1,65 @@
---
title: Cloning repository
description: Get the code to your local machine and start developing your extension.
url: /docs/extension/installation/clone
---
# Cloning repository
<Callout type="info" title="Prerequisite: Git installed">
Ensure you have Git installed on your local machine before proceeding. You can download Git from [here](https://git-scm.com).
</Callout>
## Git clone
Clone the repository using the following command:
```bash
git clone git@github.com:turbostarter/core
```
By default, we're using [SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) for all Git commands. If you don't have it configured, please refer to the [official documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) to set it up.
Alternatively, you can use HTTPS to clone the repository:
```bash
git clone https://github.com/turbostarter/core
```
Another alternative could be to use the [Github CLI](https://cli.github.com/) or [Github Desktop](https://desktop.github.com/) for Git operations.
<Card title="Git clone" description="git-scm.com" href="https://git-scm.com/docs/git-clone" />
## Git remote
After cloning the repository, remove the original origin remote:
```bash
git remote rm origin
```
Add the upstream remote pointing to the original repository to pull updates:
```bash
git remote add upstream git@github.com:turbostarter/core
```
Once you have your own repository set up, add your repository as the origin:
```bash
git remote add origin <your-repository-url>
```
<Card title="Git remote" description="git-scm.com" href="https://git-scm.com/docs/git-remote" />
## Staying up to date
To pull updates from the upstream repository, run the following command daily (preferably with your morning coffee ☕):
```bash
git pull upstream main
```
This ensures your repository stays up to date with the latest changes.
Check [Updating codebase](/docs/web/installation/update) for more details on updating your codebase.

353
.context/turbostarter-framework-context/sections/extension/installation/commands.md Normal file
View File

@@ -0,0 +1,353 @@
---
title: Common commands
description: Learn about common commands you need to know to work with the extension project.
url: /docs/extension/installation/commands
---
# Common commands
<Callout>
For sure, you don't need these commands to kickstart your project, but it's useful to know they exist for when you need them.
</Callout>
<Callout title="Want shorter commands?">
You can set up aliases for these commands in your shell configuration file. For example, you can set up an alias for `pnpm` to `p`:
```bash title="~/.bashrc"
alias p='pnpm'
```
Or, if you're using [Zsh](https://ohmyz.sh/), you can add the alias to `~/.zshrc`:
```bash title="~/.zshrc"
alias p='pnpm'
```
Then run `source ~/.bashrc` or `source ~/.zshrc` to apply the changes.
You can now use `p` instead of `pnpm` in your terminal. For example, `p i` instead of `pnpm install`.
</Callout>
<Callout title="Injecting environment variables">
To inject environment variables into the command you run, prefix it with `with-env`:
```bash
pnpm with-env <command>
```
For example, `pnpm with-env pnpm build` will run `pnpm build` with the environment variables injected.
Some commands, like `pnpm dev`, automatically inject the environment variables for you.
</Callout>
## Installing dependencies
To install the dependencies, run:
```bash
pnpm install
```
## Starting development server
Start development server by running:
```bash
pnpm dev
```
## Building project
To build the project (including all apps and packages), run:
```bash
pnpm build
```
## Building specific app/package
To build a specific app/package, run:
```bash
pnpm turbo build --filter=<package-name>
```
## Cleaning project
To clean the project, run:
```bash
pnpm clean
```
Then, reinstall the dependencies:
```bash
pnpm install
```
## Formatting code
To check for formatting errors using Prettier, run:
```bash
pnpm format
```
To fix formatting errors using Prettier, run:
```bash
pnpm format:fix
```
## Linting code
To check for linting errors using ESLint, run:
```bash
pnpm lint
```
To fix linting errors using ESLint, run:
```bash
pnpm lint:fix
```
## Typechecking
To typecheck the code using TypeScript for any type errors, run:
```bash
pnpm typecheck
```
## Adding UI components
<Tabs items={["Web", "Mobile"]}>
<Tab value="Web">
To add a new web component, run:
```bash
pnpm --filter @turbostarter/ui-web ui:add
```
This command will add and export a new component to `@turbostarter/ui-web` package.
</Tab>
<Tab value="Mobile">
To add a new mobile component, run:
```bash
pnpm --filter @turbostarter/ui-mobile ui:add
```
This command will add and export a new component to `@turbostarter/ui-mobile` package.
</Tab>
</Tabs>
## Services commands
<Callout title="Prerequisite: Docker installed">
To run the services containers locally, you need to have [Docker](https://www.docker.com/) installed on your machine.
You can always use the cloud-hosted solution (e.g. [Neon](https://neon.tech/), [Turso](https://turso.tech/) for database) for your projects.
</Callout>
We have a few commands to help you manage the services containers (for local development).
### Starting containers
To start the services containers, run:
```bash
pnpm services:start
```
It will run all the services containers. You can check their configs in `docker-compose.yml`.
### Setting up services
To setup all the services, run:
```bash
pnpm services:setup
```
It will start all the services containers and run necessary setup steps.
### Stopping containers
To stop the services containers, run:
```bash
pnpm services:stop
```
### Displaying status
To check the status and logs of the services containers, run:
```bash
pnpm services:status
```
### Displaying logs
To display the logs of the services containers, run:
```bash
pnpm services:logs
```
### Database commands
We have a few commands to help you manage the database leveraging [Drizzle CLI](https://orm.drizzle.team/kit-docs/commands).
#### Generating migrations
To generate a new migration, run:
```bash
pnpm with-env turbo db:generate
```
It will create a new migration `.sql` file in the `packages/db/migrations` folder.
#### Running migrations
To run the migrations against the db, run:
```bash
pnpm with-env pnpm --filter @turbostarter/db db:migrate
```
It will apply all the pending migrations.
#### Pushing changes directly
<Callout type="warn" title="Don't mess up with your schema!">
Make sure you know what you're doing before pushing changes directly to the db.
</Callout>
To push changes directly to the db, run:
```bash
pnpm with-env pnpm --filter @turbostarter/db db:push
```
It lets you push your schema changes directly to the database and omit managing SQL migration files.
#### Checking database status
To check the status of the database, run:
```bash
pnpm with-env pnpm --filter @turbostarter/db db:status
```
It will display the status of the applied migrations and the pending ones.
```bash
Applied migrations:
- 0000_cooing_vargas
- 0001_curious_wallflower
- 0002_good_vertigo
- 0003_peaceful_devos
- 0004_fat_mad_thinker
- 0005_yummy_bucky
- 0006_glorious_vargas
Pending migrations:
- 0007_nebulous_havok
```
#### Resetting database
To reset the database, run:
```bash
pnpm with-env pnpm --filter @turbostarter/db db:reset
```
It will reset the database to the initial state.
#### Seeding database
To seed the database with some example data (for development purposes), run:
```bash
pnpm with-env turbo db:seed
```
It will populate your database with some example data.
#### Checking database
To check the database schema consistency, run:
```bash
pnpm with-env pnpm --filter @turbostarter/db db:check
```
#### Studying database
To study the database schema in the browser, run:
```bash
pnpm with-env pnpm --filter @turbostarter/db db:studio
```
This will start the Studio on [https://local.drizzle.studio](https://local.drizzle.studio).
## Tests commands
### Running tests
To run the tests, run:
```bash
pnpm test
```
This will run all the tests in the project using Turbo tasks. As it leverages Turbo caching, it's [recommended](/docs/web/tests/unit#configuration) to run it in your CI/CD pipeline.
### Running tests projects
To run tests for all Vitest [Test Projects](https://vitest.dev/guide/projects), run:
```bash
pnpm test:projects
```
This will run all the tests in the project using Vitest.
### Watching tests
To watch the tests, run:
```bash
pnpm test:projects:watch
```
This will watch the tests for all [Test Projects](https://vitest.dev/guide/projects) and run them automatically when you make changes.
### Generating code coverage
To generate code coverage report, run:
```bash
pnpm turbo test:coverage
```
This will generate a code coverage report in the `coverage` directory under `tooling/vitest` package.
### Viewing code coverage
To preview the code coverage report in the browser, run:
```bash
pnpm turbo test:coverage:view
```
This will launch the report's `.html` file in your default browser.

86
.context/turbostarter-framework-context/sections/extension/installation/conventions.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: Conventions
description: Some standard conventions used across TurboStarter codebase.
url: /docs/extension/installation/conventions
---
# Conventions
You're not required to follow these conventions: they're simply a standard set of practices used in the core kit. If you like them - we encourage you to keep these during your usage of the kit - so to have consistent code style that you and your teammates understand.
## Turborepo Packages
In this project, we use [Turborepo packages](https://turbo.build/repo/docs/core-concepts/internal-packages) to define reusable code that can be shared across multiple applications.
* **Apps** are used to define the main application, including routing, layout, and global styles.
* **Packages** shares reusable code add functionalities across multiple applications. They're configurable from the main application.
<Callout title="Should I create a new package?">
**Recommendation:** Do not create a package for your app code unless you plan to reuse it across multiple applications or are experienced in writing library code.
If your application is not intended for reuse, keep all code in the app folder. This approach saves time and reduces complexity, both of which are beneficial for fast shipping.
**Experienced developers:** If you have the experience, feel free to create packages as needed.
</Callout>
## Imports and Paths
When importing modules from packages or apps, use the following conventions:
* **From a package:** Use `@turbostarter/package-name` (e.g., `@turbostarter/ui`, `@turbostarter/api`, etc.).
* **From an app:** Use `~/` (e.g., `~/components`, `~/config`, etc.).
## Enforcing conventions
* [Prettier](https://prettier.io/) is used to enforce code formatting.
* [ESLint](https://eslint.org/) is used to enforce code quality and best practices.
* [TypeScript](https://www.typescriptlang.org/) is used to enforce type safety.
<Cards className="grid-cols-2 sm:grid-cols-3">
<Card title="Prettier" href="https://prettier.io/" description="prettier.io" />
<Card title="ESLint" href="https://eslint.org/" description="eslint.org" />
<Card title="TypeScript" href="https://www.typescriptlang.org/" description="typescriptlang.org" />
</Cards>
## Code health
TurboStarter provides a set of tools to ensure code health and quality in your project.
### Github Actions
By default, TurboStarter sets up Github Actions to run tests on every push to the repository. You can find the Github Actions configuration in the `.github/workflows` directory.
The workflow has multiple stages:
* `format` - runs Prettier to format the code.
* `lint` - runs ESLint to check for linting errors.
* `typecheck` - runs TypeScript to check for type errors.
### Git hooks
Together with TurboStarter we have set up a `commit-msg` hook which will check if your commit message follows the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) message format. This is important for generating changelogs and keeping a clean commit history.
Although we didn't ship any pre-commit hooks (we believe in shipping fast with moving checking code responsibility to CI), you can easily add them by using [Husky](https://typicode.github.io/husky/#/).
#### Setting up the Pre-Commit Hook
To do so, create a `pre-commit` file in the `./..husky` directory with the following content:
```bash
#!/bin/sh
pnpm typecheck
pnpm lint
```
Turborepo will execute the commands for all the affected packages - while skipping the ones that are not affected.
#### Make the Pre-Commit Hook Executable
```bash
chmod +x ./.husky/pre-commit
```
To test the pre-commit hook, try to commit a file with linting errors or type errors. The commit should fail, and you should see the error messages in the console.

73
.context/turbostarter-framework-context/sections/extension/installation/dependencies.md Normal file
View File

@@ -0,0 +1,73 @@
---
title: Managing dependencies
description: Learn how to manage dependencies in your project.
url: /docs/extension/installation/dependencies
---
# Managing dependencies
As the package manager we chose [pnpm](https://pnpm.io/).
<Callout title="Why pnpm?">
It is a fast, disk space efficient package manager that uses hard links and symlinks to save one version of a module only ever once on a disk. It also has a great [monorepo support](https://pnpm.io/workspaces). Of course, you can change it to use [Bun](https://bunpkg.com), [yarn](https://yarnpkg.com) or [npm](https://www.npmjs.com) with minimal effort.
</Callout>
## Install dependency
To install a package you need to decide whether you want to install it to the root of the monorepo or to a specific workspace. Installing it to the root makes it available to all packages, while installing it to a specific workspace makes it available only to that workspace.
To install a package globally, run:
```bash
pnpm add -w <package-name>
```
To install a package to a specific workspace, run:
```bash
pnpm add --filter <workspace-name> <package-name>
```
For example:
```bash
pnpm add --filter @turbostarter/ui motion
```
It will install `motion` to the `@turbostarter/ui` workspace.
## Remove dependency
Removing a package is the same as installing but with the `remove` command.
To remove a package globally, run:
```bash
pnpm remove -w <package-name>
```
To remove a package from a specific workspace, run:
```bash
pnpm remove --filter <workspace-name> <package-name>
```
## Update a package
Updating is a bit easier since there is a nice way to update a package in all workspaces at once:
```bash
pnpm update -r <package-name>
```
<Callout title="Semantic versioning">
When you update a package, pnpm will respect the [semantic versioning](https://docs.npmjs.com/about-semantic-versioning) rules defined in the `package.json` file. If you want to update a package to the latest version, you can use the `--latest` flag.
</Callout>
## Renovate bot
By default, TurboStarter comes with [Renovate](https://www.npmjs.com/package/renovate) enabled. It is a tool that helps you manage your dependencies by automatically creating pull requests to update your dependencies to the latest versions. You can find its configuration in the `.github/renovate.json` file. Learn more about it in the [official docs](https://docs.renovatebot.com/configuration-options/).
When it creates a pull request, it is treated as a normal PR, so all tests and preview deployments will run. **It is recommended to always preview and test the changes in the staging environment before merging the PR to the main branch to avoid breaking the application.**
<Card href="https://docs.renovatebot.com" title="Renovate" description="renovatebot.com" />

139
.context/turbostarter-framework-context/sections/extension/installation/development.md Normal file
View File

@@ -0,0 +1,139 @@
---
title: Development
description: Get started with the code and develop your browser extension.
url: /docs/extension/installation/development
---
# Development
## Prerequisites
To get started with TurboStarter, ensure you have the following installed and set up:
* [Node.js](https://nodejs.org/en) (22.x or higher)
* [Docker](https://www.docker.com) (only if you want to use local services e.g. database)
* [pnpm](https://pnpm.io)
## Project development
<Steps>
<Step>
### Install dependencies
Install the project dependencies by running the following command:
```bash
pnpm i
```
<Callout title="Why pnpm?">
It is a fast, disk space efficient package manager that uses hard links and symlinks to save one version of a module only ever once on a disk. It also has a great [monorepo support](https://pnpm.io/workspaces). Of course, you can change it to use [Bun](https://bunpkg.com), [yarn](https://yarnpkg.com) or [npm](https://www.npmjs.com) with minimal effort.
</Callout>
</Step>
<Step>
### Setup environment variables
Create a `.env.local` files from `.env.example` files and fill in the required environment variables.
You can use the following command to recursively copy the `.env.example` files to the `.env.local` files:
<Tabs items={["Unix (MacOS/Linux)", "Windows"]}>
<Tab value="Unix (MacOS/Linux)">
```bash
find . -name ".env.example" -exec sh -c 'cp "$1" "${1%.example}.local"' _ {} \;
```
</Tab>
<Tab value="Windows">
```bash
Get-ChildItem -Recurse -Filter ".env.example" | ForEach-Object {
Copy-Item $_.FullName ($\_.FullName -replace '\.example$', '.local')
}
```
</Tab>
</Tabs>
Check [Environment variables](/docs/extension/configuration/environment-variables) for more details on setting up environment variables.
</Step>
<Step>
### Setup services
If you want to use local services like database etc. (**recommended for development purposes**), ensure Docker is running, then setup them with:
```bash
pnpm services:setup
```
This command initiates the containers and runs necessary setup steps, ensuring your services are up to date and ready to use.
</Step>
<Step>
### Start development server
To start the application development server, run:
```bash
pnpm dev
```
Your development server should now be running 🎉
WXT will create a dev bundle for your extension and start a live-reloading development server, which will automatically update your extension bundle and reload your browser on source code changes.
It also makes the icon grayscale to distinguish between development and production extension bundles.
</Step>
<Step>
### Load the extension
<Tabs items={["Chrome", "Firefox"]}>
<Tab value="Chrome">
Head over to `chrome://extensions` and enable **Developer Mode**.
![Developer mode](/images/docs/extension/chrome/developer-mode.png)
Click on "Load Unpacked" and navigate to your extension's `apps/extension/build/chrome-mv3` directory.
To see your popup, click on the puzzle piece icon on the Chrome toolbar, and click on your extension.
![Pin to toolbar](/images/docs/extension/chrome/pin.png)
<Callout title="Pro tip">
Pin your extension to the Chrome toolbar for easy access by clicking the pin button.
</Callout>
</Tab>
<Tab value="Firefox">
Head over to `about:debugging` and click on "This Firefox".
Click on "Load Temporary Add-on" and navigate to your extension's `apps/extension/build/firefox-mv2` directory. Pick any file to load the extension.
![Load temporary add-on](/images/docs/extension/firefox/load.png)
The extension now installs, and remains installed until you restart Firefox.
To see your popup, click on your extension icon on the Firefox toolbar.
![Popup](/images/docs/extension/firefox/popup.png)
<Callout>
Loaded extension starts as pinned on the Firefox toolbar. Don't remove it to easily access it later.
</Callout>
</Tab>
</Tabs>
<Callout title="Automatic browser startup">
You can also configure your development server to automatically start the browser when you start the server. To do it, create a `web-ext.config.ts` file in a root of your extension and configure it with your browser [binaries](https://wxt.dev/guide/essentials/config/browser-startup.html#set-browser-binaries) and [argumens](https://wxt.dev/guide/essentials/config/browser-startup.html#persist-data).
Learn more in the [official documentation](https://wxt.dev/guide/essentials/config/browser-startup.html).
</Callout>
</Step>
<Step>
### Publish to stores
When you're ready to publish the project to the stores, follow the [guidelines](/docs/extension/marketing) and [checklist](/docs/extension/publishing/checklist) to ensure everything is set up correctly.
</Step>
</Steps>

69
.context/turbostarter-framework-context/sections/extension/installation/editor-setup.md Normal file
View File

@@ -0,0 +1,69 @@
---
title: Editor setup
description: Learn how to set up your editor for the fastest development experience.
url: /docs/extension/installation/editor-setup
---
# Editor setup
Of course you can use every IDE you like, but you will have the best possible developer experience with this starter kit when using **VSCode-based** editor with the suggested settings and extensions.
## Settings
We have included most recommended settings in the `.vscode/settings.json` file to make your development experience as smooth as possible. It include mostly configs for tools like Prettier, ESLint and Tailwind which are used to enforce some conventions across the codebase. You can adjust them to your needs.
## LLM rules
We exposed a special endpoint that will scan all the docs and return the content as a text file which you can use to train your LLM or put in a prompt. You can find it at [/llms.txt](/llms.txt).
The repository also includes a custom rules for most popular AI editors and agents to ensure that AI completions are working as expected and following our conventions.
### AGENTS.md
We've integrated specific rules that help maintain code quality and ensure AI-assisted completions align with our project standards.
You can find them in the `AGENTS.md` file at the root of the project. This format is a standardized way to instruct AI agents to follow project conventions when generating code and it's used by over **20,000** open-source projects - including [Cursor](https://cursor.sh/), [Aider](https://aider.chat/), [Codex from OpenAI](https://openai.com/blog/openai-codex/), [Jules from Google](https://jules.ai/), [Windsurf](https://windsurf.dev/), and many others.
```md title="AGENTS.md"
### Code Style and Structure
- Write concise, technical TypeScript code with accurate examples
- Use functional and declarative programming patterns; avoid classes
- Prefer iteration and modularization over code duplication
### Naming Conventions
....
```
To learn more about `AGENTS.md` rules check out the [official documentation](https://agents.md/).
## Extensions
Once you cloned the project and opened it in VSCode you should be promted to install suggested extensions which are defined in the `.vscode/extensions.json` automatically. In case you rather want to install them manually you can do so at any time later.
These are the extensions we recommend:
### ESLint
Global extension for static code analysis. It will help you to find and fix problems in your JavaScript code.
<Card title="Download ESLint" href="https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint" description="marketplace.visualstudio.com" />
### Prettier
Global extension for code formatting. It will help you to keep your code clean and consistent.
<Card title="Download Prettier" href="https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode" description="marketplace.visualstudio.com" />
### Pretty TypeScript Errors
Improves TypeScript error messages shown in the editor.
<Card title="Download Pretty TypeScript Errors" href="https://marketplace.visualstudio.com/items?itemName=yoavbls.pretty-ts-errors" description="marketplace.visualstudio.com" />
### Tailwind CSS IntelliSense
Adds IntelliSense for Tailwind CSS classes to enable autocompletion and linting.
<Card title="Download Tailwind CSS IntelliSense" href="https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss" description="marketplace.visualstudio.com" />

128
.context/turbostarter-framework-context/sections/extension/installation/structure.md Normal file
View File

@@ -0,0 +1,128 @@
---
title: Project structure
description: Learn about the project structure and how to navigate it.
url: /docs/extension/installation/structure
---
# Project structure
The main directories in the project are:
* `apps` - the location of the main apps
* `packages` - the location of the shared code and the API
### `apps` Directory
This is where the apps live. It includes web app (Next.js), mobile app (React Native - Expo), and the browser extension (WXT - Vite + React). Each app has its own directory.
### `packages` Directory
This is where the shared code and the API for packages live. It includes the following:
* shared libraries (database, mailers, cms, billing, etc.)
* shared features (auth, mails, billing, ai etc.)
* UI components (buttons, forms, modals, etc.)
All apps can use and reuse the API exported from the packages directory. This makes it easy to have one, or many apps in the same codebase, sharing the same code.
## Repository structure
By default the monorepo contains the following apps and packages:
<Files>
<Folder name="apps" defaultOpen>
<Folder name="web - Web app (Next.js)" />
<Folder name="mobile - Mobile app (React Native - Expo)" />
<Folder name="extension - Browser extension (WXT - Vite + React)" />
</Folder>
<Folder name="packages" defaultOpen>
<Folder name="analytics - Analytics setup" />
<Folder name="api - API server (including all features logic)" />
<Folder name="auth - Authentication setup" />
<Folder name="billing - Billing config and providers" />
<Folder name="cms - CMS setup and providers" />
<Folder name="db - Database setup" />
<Folder name="email - Mail templates and providers" />
<Folder name="i18n - Internationalization setup" />
<Folder name="shared - Shared utilities and helpers" />
<Folder name="storage - Storage setup" />
<Folder name="ui - Atomic UI components">
<Folder name="shared" />
<Folder name="web" />
<Folder name="mobile" />
</Folder>
</Folder>
<Folder name="tooling" defaultOpen>
<Folder name="eslint - ESLint config" />
<Folder name="github - Github actions" />
<Folder name="prettier - Prettier config" />
<Folder name="typescript - TypeScript config" />
</Folder>
</Files>
## Browser extension application structure
The browser extension application is located in the `apps/extension` folder. It contains the following folders:
<Files>
<Folder name="src" defaultOpen>
<Folder name="app" defaultOpen>
<Folder name="background - Background service worker" />
<Folder name="content - Content scripts" />
<Folder name="devtools - Devtools page with custom panels" />
<Folder name="newtab - New tab page" />
<Folder name="options - Options page" />
<Folder name="popup - Popup window" />
<Folder name="sidepanel - Side panel" />
<Folder name="tabs - Custom pages shipped with the extension" />
</Folder>
<Folder name="assets - Optimized static assets" />
<Folder name="config - App config" />
<Folder name="lib - Communication with packages" />
<Folder name="modules - Application modules" />
</Folder>
<File name=".env.local" />
<File name="env.config.ts" />
<File name="eslint.config.js" />
<File name="package.json" />
<File name="tsconfig.json" />
<File name="turbo.json" />
<File name="wxt.config.ts" />
</Files>

97
.context/turbostarter-framework-context/sections/extension/installation/update.md Normal file
View File

@@ -0,0 +1,97 @@
---
title: Updating codebase
description: Learn how to update your codebase to the latest version.
url: /docs/extension/installation/update
---
# Updating codebase
If you've been following along with our previous guides, you should already have a Git repository set up for your project, with an `upstream` remote pointing to the original repository.
Updating your project involves fetching the latest changes from the `upstream` remote and merging them into your project. Let's dive into the steps!
<Steps>
<Step>
## Stash changes
<Callout title="Don't have changes?">
If you don't have any changes to stash, you can skip this step and proceed with the update process.
Alternatively, you can [commit](https://git-scm.com/docs/git-commit) your changes.
</Callout>
If you have any uncommitted changes, stash them before proceeding. It will allow you to avoid any conflicts that may arise during the update process.
```bash
git stash
```
This command will save your changes in a temporary location, allowing you to retrieve them later. Once you're done updating, you can apply the stash to your working directory.
```bash
git stash apply
```
</Step>
<Step>
## Pull changes
Pull the latest changes from the `upstream` remote.
```bash
git pull upstream main
```
When prompted the first time, please opt for merging instead of rebasing.
Don't forget to run `pnpm i` in case there are any updates in the dependencies.
</Step>
<Step>
## Resolve conflicts
If there are any conflicts during the merge, Git will notify you. You can resolve them by opening the conflicting files in your code editor and making the necessary changes.
<Callout title="Conflicts in pnpm-lock.yaml?">
If you find conflicts in the `pnpm-lock.yaml file`, accept either of the two changes (avoid manual edits), then run:
```bash
pnpm i
```
Your lock file will now reflect both your changes and the updates from the upstream repository.
</Callout>
</Step>
<Step>
## Run a health check
After resolving the conflicts, it's time to test your project to ensure everything is working as expected. Run your project locally and navigate through the various features to verify that everything is functioning correctly.
For a quick health check, you can run:
```bash
pnpm lint
pnpm typecheck
```
If everything looks good, you're all set! Your project is now up to date with the latest changes from the `upstream` repository.
</Step>
<Step>
## Commit and push
Once everything is working fine, don't forget to commit your changes using:
```bash
git commit -m "<your-commit-message>"
```
and push them to your remote repository with:
```bash
git push origin <your-branch-name>
```
</Step>
</Steps>

175
.context/turbostarter-framework-context/sections/extension/internationalization.md Normal file
View File

@@ -0,0 +1,175 @@
---
title: Internationalization
description: Learn how to internationalize your extension.
url: /docs/extension/internationalization
---
# Internationalization
Turbostarter's extension uses [i18next](https://www.i18next.com/) and web cookies to store the language preference of the user. This allows the extension to be fully internationalized.
<Callout title="Why this combination?">
We use i18next because it's a robust and widely-adopted internationalization framework that works seamlessly with React.
The combination with web cookies allows us to persistently store language preferences across all extension contexts and share it with the web app while maintaining excellent performance and browser compatibility.
</Callout>
![i18next logo](/images/docs/i18next.jpg)
## Configuration
The global configuration is defined in the `@turbostarter/i18n` package and shared across all applications. You can read more about it in the [web configuration](/docs/web/internationalization/configuration) documentation.
By default, the locale is automatically detected based on the user's device settings. You can override it and set the default locale of your mobile app in the [app configuration](/docs/extension/configuration/app) file.
Also, the locale configuration is **shared between the web app and the extension** (same as [session](/docs/extension/auth/session)), which means that changing the locale in one place will automatically update it in the other. It's a common pattern for modern apps, simplifying the user experience and reducing the maintenance effort.
### Cookies
When a user first opens the [web app](/docs/web), the locale is detected and a cookie is set. This cookie is used to remember the user's language preference.
You can find its value in the *Cookies* tab of the developer tools of your browser:
![Locale cookie](/images/docs/extension/locale-cookie.png)
To enable your extension to read the cookie and that way share the locale settings with the web app, you need to set the cookies permission in the `wxt.config.ts` under `manifest.permissions` field:
```ts
export default defineConfig({
manifest: {
permissions: ["cookies"],
},
});
```
And to be able to read the cookie from your app url, you need to set host\_permissions, which will include your app url:
```ts
export default defineConfig({
manifest: {
host_permissions: ["http://localhost/*", "https://your-app-url.com/*"],
},
});
```
Then you would be able to share the cookie between your apps and also read its value using `browser.cookies` API.
<Callout title="Avoid &#x22;<all_urls>&#x22;" type="warn">
Avoid using `<all_urls>` in `host_permissions`. It affects all urls and may cause security issues, as well as a [rejection](https://developer.chrome.com/docs/webstore/review-process#review-time-factors) from the destination store.
</Callout>
<Cards>
<Card title="Declare permissions" href="https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions" description="developer.chrome.com" />
<Card title="chrome.cookies" href="https://developer.chrome.com/docs/extensions/reference/api/cookies" description="developer.chrome.com" />
</Cards>
## Translating extension
To translate individual components and screens, you can use the well-known `useTranslation` hook.
```tsx
import { useTranslation } from "@turbostarter/i18n";
export const Popup = () => {
const { t } = useTranslation();
return <div>{t("hello")}</div>;
};
```
That's the recommended way to translate stuff inside your extension.
### Store presence
As we saw in the [manifest](/docs/extension/configuration/manifest#locales) section, you can also localize your extension's store presence (like title, description, and other metadata). This allows you to customize how your extension appears in different web stores based on the user's language.
Each store has specific requirements for localization:
* [Chrome Web Store](https://developer.chrome.com/docs/webstore/cws-dashboard-listing/) requires a `_locales` directory with JSON files for each language
* [Firefox Add-ons](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization) uses a similar structure but with some differences in the manifest
* [Edge Add-ons](https://learn.microsoft.com/en-us/microsoft-edge/extensions/publish/publish-extension#supporting-multiple-languages) uses the same structure as Chrome Web Store
Although most of the config is abstracted behind common structure, please follow the store-specific guides below for detailed instructions on setting up localization for your extension's store listing.
<Cards>
<Card title="I18n - WXT" href="https://wxt.dev/guide/essentials/i18n.html" description="wxt.dev" />
<Card title="Chrome Web Store" href="https://developer.chrome.com/docs/webstore/cws-dashboard-listing" description="developer.chrome.com" />
<Card title="Firefox Add-ons" href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization" description="developer.mozilla.org" />
<Card title="Edge Add-ons" href="https://learn.microsoft.com/en-us/microsoft-edge/extensions/publish/publish-extension#supporting-multiple-languages" description="developer.microsoft.com" />
</Cards>
## Language switcher
TurboStarter ships with a language customizer component that allows users to switch between languages in your extension. You can import and use the `LocaleCustomizer` component in your popup, options page, or any other extension view:
```tsx
import { LocaleCustomizer } from "@turbostarter/ui-web/i18n";
export const Popup = () => {
return <LocaleCustomizer />;
};
```
<Callout title="This will change the locale of the web app as well" type="warn">
As the web app and extension share the same i18n configuration (cookie), changing the language in one will affect the other. **This is intentional** and ensures a consistent experience across both platforms, since your extension likely serves as a companion to the web app and should maintain the same language preferences.
</Callout>
## Best practices
Here are key best practices for managing translations in your browser extension:
* Use descriptive, hierarchical translation keys
```ts
// ✅ Good
"popup.settings.language";
"content.toolbar.save";
// ❌ Bad
"saveButton";
"text1";
```
* Organize translations by extension views and features
```
_locales/
├── en/
│ ├── messages.json
│ ├── popup.json
│ └── options.json
└── es/
├── messages.json
├── popup.json
└── options.json
```
* Handle fallback languages gracefully
* Keep manifest descriptions localized for store listings
* Consider context in translations:
```ts
// Context-aware messages
t("button.save", { context: "document" }); // "Save document"
t("button.save", { context: "settings" }); // "Apply changes"
```
* Use placeholders for dynamic content:
```ts
// With variables
t("status.saved", { time: "2 minutes ago" }); // "Last saved 2 minutes ago"
// With plurals
t("items", { count: 5 }); // "5 items"
```
* Keep translations in sync between extension views
* Cache translations for offline functionality

63
.context/turbostarter-framework-context/sections/extension/marketing.md Normal file
View File

@@ -0,0 +1,63 @@
---
title: Marketing
description: Learn how to market your mobile application.
url: /docs/extension/marketing
---
# Marketing
As you saw in the [Extras](/docs/extension/extras) section, TurboStarter comes with a lot of tips and tricks to make your product better and help you launch your extension faster with higher traffic.
The same applies to [submission tips](/docs/extension/extras#submission-tips) to help you get your extension approved by the browser stores faster.
We'll talk more about the whole process of deploying and publishing your extension in the [Publishing](/docs/extension/publishing/checklist) section, here we'll go through some guidelines that you need to follow to make your store's visibility higher.
## Before you submit
To help your extension approval go as smoothly as possible, review the common missteps listed below that can slow down the review process or trigger a rejection. This doesn't replace the official guidelines or guarantee approval, but making sure you can check every item on the list is a good start.
Make sure you:
* Test your extension thoroughly for crashes and bugs
* Ensure that all extension information and metadata is complete and accurate
* Update your contact information in case the review team needs to reach you
* Provide clear instructions on how to use your extension, including any special setup required
* If your extension requires an account, provide a demo account or a way to test all features without signing up
* Enable and test all backend services to ensure they're live and accessible during review
* Include detailed explanations of non-obvious features in the extension description
* Ensure your extension complies with the specific browser store's policies (e.g., [Chrome Web Store](https://developer.chrome.com/docs/webstore/program-policies/best-practices), [Firefox Add-ons](https://extensionworkshop.com/documentation/publish/add-on-policies/), [Edge Add-ons](https://learn.microsoft.com/en-us/legal/microsoft-edge/extensions/developer-policies) etc.)
* Remove any references to features not supported in browser extensions (e.g., in-app purchases)
Following these basic steps during development and before submission will help you get your extension approved faster and with fewer issues.
## Guidelines
Each store has slightly different guidelines, but some of them are general and can be applied to all stores:
* **Security**: Your extension must not contain malicious code or behavior that can harm users' devices or data.
* **Performance**: Your extension must be performant and stable, with a smooth user experience.
* **Privacy**: Your extension must respect user privacy and not collect unnecessary data without explicit consent.
* **Compliance**: Your extension must comply with all relevant laws and regulations.
You can read more about official guidelines for each store in the following links:
* [Chrome Web Store](https://developer.chrome.com/docs/webstore/program-policies/best-practices)
* [Firefox Add-ons](https://extensionworkshop.com/documentation/publish/add-on-policies/)
* [Edge Add-ons](https://learn.microsoft.com/en-us/microsoft-edge/extensions/developer-guide/best-practices)
## Common mistakes
There are a few common mistakes that you should avoid to make sure your extension can be accepted in the stores. The most common ones are:
* **Not enough description** - make sure to describe all the features of your extension and how it works in your store listing, that way users won't be confused about what your extension does. Also include detailed information in the single purpose field regarding your extension's primary functionality.
* **Privacy issues** - respect user privacy and require as least permissions as possible, don't ask for permissions that are not necessary for your extension to work
* **Customer support** - provide a way to contact you in case the user has any issues with your extension
* **Stay up-to-date** - keep your extension and its documentation up-to-date to ensure a smooth user experience and to prevent issues during the review process.
<Cards>
<Card href="https://developer.chrome.com/docs/webstore/program-policies/best-practices" title="Best Practices and Guidelines" description="developer.chrome.com" />
<Card href="https://extensionworkshop.com/documentation/publish/add-on-policies/" title="Add-on Policies" description="extensionworkshop.com" />
<Card href="https://learn.microsoft.com/en-us/legal/microsoft-edge/extensions/developer-policies" title="Developer Policies" description="learn.microsoft.com" />
</Cards>

143
.context/turbostarter-framework-context/sections/extension/monitoring/overview.md Normal file
View File

@@ -0,0 +1,143 @@
---
title: Overview
description: Get started with browser extension monitoring in TurboStarter.
url: /docs/extension/monitoring/overview
---
# Overview
TurboStarter includes powerful, provider-agnostic monitoring helpers for the browser extension so you can understand **what failed**, **where it failed** (popup, content script, background), and **who it impacted**. The API is intentionally designed for simplicity and extensibility, so you can swap providers without rewriting your extension code.
## Capturing exceptions
Extensions have multiple runtimes. To get good coverage, capture errors in the places users actually feel them:
* **Popup / options UI**: React pages where runtime errors break interactions.
* **Background (service worker)**: long-lived logic like alarms, message routing, and sync.
* **Content scripts**: page integrations where DOM differences and CSP can trigger failures.
* **Manual reporting**: wrap critical flows (auth, billing, webhooks-to-extension sync, imports) with `try/catch` and report with context.
<Tabs items={["Popup / options", "Background", "Content script"]}>
<Tab value="Popup / options">
```tsx
import { captureException } from "@turbostarter/monitoring-extension";
export function ExampleButton() {
const onPress = async () => {
try {
/* some risky operation */
} catch (error) {
captureException(error);
}
};
return <button onClick={onPress}>Trigger Exception</button>;
}
```
</Tab>
<Tab value="Background">
```ts
import { captureException } from "@turbostarter/monitoring-extension";
browser.runtime.onMessage.addListener((message, _sender, sendResponse) => {
try {
/* handle message */
sendResponse({ ok: true });
} catch (error) {
captureException(error);
sendResponse({ ok: false });
}
});
```
</Tab>
<Tab value="Content script">
```ts
import { captureException } from "@turbostarter/monitoring-extension";
try {
/* interact with the page DOM */
} catch (error) {
captureException(error);
}
```
</Tab>
</Tabs>
<Callout type="warn" title="Don't rely on a single runtime">
An exception in a content script won't automatically show up in your background logs (and vice versa). Add capture points in each runtime you ship, especially if you do message passing between them.
</Callout>
## Identifying users
Monitoring becomes far more useful once reports can be tied to a stable identity. In extensions you often have two “identities”:
* **Anonymous, stable install id**: useful before sign-in (and to correlate issues with a device/install).
* **Signed-in user**: once the user authenticates, identify with their user id so issues map to a real account.
TurboStarter's monitoring layer supports identifying the current user when your auth session resolves. When signed out, pass `null` (or your provider's preferred anonymous identity strategy).
```tsx title="monitoring.tsx"
import { useEffect } from "react";
import { identify } from "@turbostarter/monitoring-extension";
import { authClient } from "~/lib/auth/client";
export const MonitoringProvider = ({
children,
}: {
children: React.ReactNode;
}) => {
const session = authClient.useSession();
useEffect(() => {
if (session.isPending) {
return;
}
identify(session.data?.user ?? null);
}, [session]);
return <>{children}</>;
};
```
<Callout title="Privacy defaults" type="error">
Prefer **stable IDs** over PII. Only attach traits that help debugging (plan, role, extension version) and avoid secrets (tokens, passwords) or sensitive fields unless you've explicitly chosen to send them.
</Callout>
## Providers
The starter supports multiple monitoring providers behind the same API, so you can start with one and switch later.
<Cards>
<Card title="Sentry" href="/docs/extension/monitoring/sentry" />
<Card title="PostHog" href="/docs/extension/monitoring/posthog" />
</Cards>
## Best practices
<Cards>
<Card title="Include runtime + version context" className="shadow-none">
Extension issues are often environment-specific. Make sure you can filter by
runtime (popup/background/content script), extension version, and browser.
</Card>
<Card title="Capture actionable failures" className="shadow-none">
Focus on crashes and failures that break core flows; skip “expected” states
like validation errors or user cancellations.
</Card>
<Card title="Dedupe noisy loops" className="shadow-none">
Background alarms, retries, and message loops can generate many identical
errors. Guard your capture calls to keep signal high (and costs low).
</Card>
<Card title="Keep environments separate" className="shadow-none">
Don't mix dev/beta/stable releases. Tag builds so you can correlate spikes
with a rollout and verify fixes quickly.
</Card>
</Cards>
With capture points in each runtime, user identification wired up, and a provider configured, extension monitoring becomes a tight feedback loop: you can spot regressions early, understand which surface area is failing and validate fixes confidently as you ship new versions.

167
.context/turbostarter-framework-context/sections/extension/monitoring/posthog.md Normal file
View File

@@ -0,0 +1,167 @@
---
title: PostHog
description: Learn how to setup PostHog as your browser extension monitoring provider.
url: /docs/extension/monitoring/posthog
---
# PostHog
[PostHog](https://posthog.com/) is a product analytics platform that also supports monitoring capabilities like error tracking and session replay. In extensions, it's especially useful when you want to connect “what broke” with “what the user did” right before the issue occurred.
TurboStarter keeps monitoring behind a unified API, so you can route exception captures from your popup, background, and content scripts to PostHog without rewriting the call sites.
<Callout type="warn" title="Prerequisite: PostHog account">
To use PostHog as your monitoring provider, you'll need a PostHog instance. You can use [PostHog Cloud](https://app.posthog.com/signup) or [self-host](https://posthog.com/docs/self-host).
</Callout>
<Callout type="info" title="You can also use it for extension analytics">
PostHog is also supported as an analytics provider for the extension. If you want to track in-extension events, see the [analytics overview](/docs/extension/analytics/overview) and the [PostHog analytics configuration](/docs/extension/analytics/configuration#posthog).
</Callout>
![PostHog banner](/images/docs/web/monitoring/posthog/banner.jpg)
## Configuration
Here you'll configure PostHog as the monitoring provider for your extension so exceptions from the popup, background/service worker, and content scripts show up with enough context to debug.
<Steps>
<Step>
### Create a project
Create a PostHog [project](https://app.posthog.com/project/settings) for your extension. You can do this from the [PostHog dashboard](https://app.posthog.com) via the *New Project* action.
</Step>
<Step>
### Activate PostHog as your monitoring provider
TurboStarter picks the extension monitoring provider through exports in the monitoring package. To route captures to PostHog, export the PostHog implementation from the extension monitoring entrypoint:
```ts title="index.ts"
// [!code word:posthog]
export * from "./posthog";
export * from "./posthog/env";
```
</Step>
<Step>
### Set environment variables
Add your PostHog project key (and host, if you're not using the default cloud region) to your extension env. Set these locally and in whatever build environment produces your extension bundles:
```dotenv title="apps/extension/.env.local"
VITE_POSTHOG_KEY="your-posthog-project-api-key"
VITE_POSTHOG_HOST="https://us.i.posthog.com"
```
</Step>
</Steps>
That's it — load the extension, trigger a test error from the popup/background/content script, and confirm events are arriving in your PostHog project.
![PostHog error](/images/docs/web/monitoring/posthog/error.png)
If you want to go beyond basic capture (session replay, feature flags, richer context), follow PostHog's web/extension guidance.
<Cards>
<Card title="Error tracking" href="https://posthog.com/docs/error-tracking" description="posthog.com" />
<Card title="Web error tracking installation" href="https://posthog.com/docs/error-tracking/installation/web" description="posthog.com" />
</Cards>
## Uploading source maps
**Source maps** map the minified/bundled JavaScript shipped with your extension back to your original source code. Without them, stack traces in PostHog often point at compiled output, which makes debugging much slower.
<Callout>
PostHog’s source map flow for web builds relies on injecting metadata into the bundled assets. You must deploy/ship the injected assets, otherwise PostHog can’t match captured errors to the uploaded symbol sets.
</Callout>
For extensions built with Vite (which [WXT](https://wxt.dev/) is using under the hood), the high-level flow is:
* generate `.map` files during the production build
* inject PostHog metadata into the built assets
* upload the injected source maps to PostHog
<Steps>
<Step>
### Install the PostHog CLI
Install the CLI globally:
```bash
npm install -g @posthog/cli
```
</Step>
<Step>
### Authenticate the CLI
Authenticate interactively:
```bash
posthog-cli login
```
In CI, you can authenticate with environment variables:
```dotenv
POSTHOG_CLI_HOST="https://us.posthog.com"
POSTHOG_CLI_ENV_ID="your-posthog-project-id"
POSTHOG_CLI_TOKEN="your-personal-api-key"
```
</Step>
<Step>
### Build with source maps enabled
Make sure your extension build outputs source maps by modifying your `wxt.config.ts` file.
```ts title="wxt.config.ts"
import { defineConfig } from "wxt";
export default defineConfig({
/* existing WXT configuration options */
vite: () => ({
build: {
sourcemap: "hidden", // [!code ++] Source map generation must be turned on ("hidden", true, etc.)
},
}),
});
```
After building, you should have `.js` and `.js.map` files in your output directory.
</Step>
<Step>
### Inject PostHog metadata into the built assets
Inject release/chunk metadata so PostHog can associate uploaded maps with the shipped bundles:
```bash
posthog-cli sourcemap inject --directory ./path/to/assets --project my-extension --version 1.2.3
```
</Step>
<Step>
### Upload source maps
Upload the injected source maps to PostHog:
```bash
posthog-cli sourcemap upload --directory ./path/to/assets
```
</Step>
<Step>
### Verify injection and uploads
After deployment, confirm your production bundles include the injected comment (for example `//# chunkId=...`) and verify symbol sets exist in your PostHog project settings.
</Step>
</Steps>
With this in place, PostHog can symbolicate extension errors (popup/options UI, background/service worker, and content scripts) so stack traces point back to your original source files.
<Cards>
<Card title="What are source maps?" href="https://web.dev/articles/source-maps" description="web.dev" />
<Card title="Upload source maps for web" href="https://posthog.com/docs/error-tracking/upload-source-maps/web" description="posthog.com" />
</Cards>

149
.context/turbostarter-framework-context/sections/extension/monitoring/sentry.md Normal file
View File

@@ -0,0 +1,149 @@
---
title: Sentry
description: Learn how to setup Sentry as your browser extension monitoring provider.
url: /docs/extension/monitoring/sentry
---
# Sentry
[Sentry](https://sentry.io/) is a popular error monitoring and performance tracking platform. It helps you catch and debug issues by collecting exceptions, stack traces, and helpful context from production.
For browser extensions, that context matters even more: errors can happen in multiple runtimes (popup/options UI, background/service worker, and content scripts). Sentry makes it easier to see what failed and where it happened so you can ship fixes with confidence.
<Callout type="warn" title="Prerequisite: Sentry account">
To use Sentry, create an account and a project first. You can sign up [here](https://sentry.io/signup).
</Callout>
![Sentry banner](/images/docs/web/monitoring/sentry/banner.png)
## Configuration
This section walks you through enabling Sentry for your extension and verifying that errors from the popup, background/service worker, and content scripts are captured reliably.
<Steps>
<Step>
### Create a project
Create a Sentry [project](https://docs.sentry.io/product/projects/) for the extension (JavaScript / browser). You can do this from the Sentry [projects dashboard](https://sentry.io/settings/account/projects/) via the *Create Project* flow.
</Step>
<Step>
### Activate Sentry as your monitoring provider
TurboStarter picks the extension monitoring provider via exports in the monitoring package. To enable Sentry, export the Sentry implementation from the extension monitoring entrypoint:
```ts title="index.ts"
// [!code word:sentry]
export * from "./sentry";
export * from "./sentry/env";
```
If you need to customize behavior, the provider implementation lives under `packages/monitoring/extension/src/providers/sentry`.
</Step>
<Step>
### Set environment variables
From your Sentry project settings, add the DSN and environment to your extension env file (and to any [CI/build step](/docs/extension/publishing/checklist#build-your-app) that produces your extension bundles):
```dotenv title="apps/extension/.env.local"
VITE_SENTRY_DSN="your-sentry-dsn"
VITE_SENTRY_ENVIRONMENT="your-project-environment"
```
</Step>
</Steps>
That's it — load the extension, trigger a test error from the popup/background/content script, and confirm it shows up in your [Sentry dashboard](https://sentry.io/settings/account/projects/).
![Sentry error](/images/docs/web/monitoring/sentry/error.jpg)
For advanced options (sampling, releases, extra context), refer to [Sentry's JavaScript docs](https://docs.sentry.io/platforms/javascript/).
<Cards>
<Card title="Quick Start" href="https://docs.sentry.io/platforms/javascript/" description="docs.sentry.io" />
<Card title="Manual Setup" href="https://docs.sentry.io/platforms/javascript/install/npm/" description="docs.sentry.io" />
</Cards>
## Uploading source maps
**Source maps** map the bundled/minified JavaScript shipped with your extension back to your original source files. Without them, Sentry stack traces often point to compiled output, which makes debugging across popup/background/content-script runtimes much harder.
<Callout>
Generating source maps can expose your source code if `.map` files are publicly accessible. Prefer hidden source maps and/or delete them after upload.
</Callout>
Sentry can automatically provide readable stack traces for errors using source maps, requiring a [Sentry auth token](https://docs.sentry.io/account/auth-tokens/).
<Steps>
<Step>
### Install the Sentry Vite plugin
Install the package `@sentry/vite-plugin` in `apps/extension/package.json` as a dev dependency.
```bash
pnpm i @sentry/vite-plugin -D --filter extension
```
</Step>
<Step>
### Add an auth token for uploads
Create an [auth token in Sentry](https://docs.sentry.io/account/auth-tokens/) and provide it as an environment variable during builds (locally and in your build environment):
```dotenv
SENTRY_AUTH_TOKEN="your-sentry-auth-token"
```
</Step>
<Step>
### Enable source maps and configure the plugin
Enable source map generation in your extension build and add `sentryVitePlugin` **after** your other Vite plugins:
```ts title="wxt.config.ts"
import { defineConfig } from "wxt";
import { sentryVitePlugin } from "@sentry/vite-plugin";
export default defineConfig({
/* existing WXT configuration options */
vite: () => ({
build: {
sourcemap: "hidden", // [!code ++] Source map generation must be turned on ("hidden", true, etc.)
},
plugins: [
sentryVitePlugin({
org: "your-sentry-org",
project: "your-sentry-project",
authToken: process.env.SENTRY_AUTH_TOKEN,
sourcemaps: {
// As you're enabling client source maps, you probably want to delete them after they're uploaded to Sentry.
// Set the appropriate glob pattern for your output folder - some glob examples below:
filesToDeleteAfterUpload: [
"./**/*.map",
".*/**/public/**/*.map",
"./dist/**/client/**/*.map",
],
},
}),
],
}),
});
```
</Step>
<Step>
### Verify uploads with a production build
The Sentry Vite plugin doesn't upload in dev/watch mode. Run a production build, then trigger a test error in the extension and confirm stack traces resolve to your original source.
</Step>
</Steps>
Once this is in place, errors from your extension's compiled bundles (popup/options UI, background/service worker, content scripts) should show **readable stack traces** in Sentry, without shipping source maps to end users.
<Cards>
<Card title="What are source maps?" href="https://web.dev/articles/source-maps" description="web.dev" />
<Card title="Sentry Vite plugin" href="https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/vite/" description="docs.sentry.io" />
</Cards>

63
.context/turbostarter-framework-context/sections/extension/organizations.md Normal file
View File

@@ -0,0 +1,63 @@
---
title: Organizations/teams
description: Learn how to use organizations/teams/multi-tenancy in TurboStarter extension.
url: /docs/extension/organizations
---
# Organizations/teams
TurboStarter extensions support organizations/teams out of the box by sharing the same authentication session as your web app. The active organization is stored in the session and available to your extension without re-implementing organizations logic.
<Callout type="info" title="Shared session and tenant context">
The extension and web app use a single auth session powered by Better Auth. The session includes tenant context (for example, `activeOrganizationId`). When users sign in, switch organizations, or sign out in the web app, the extension picks up these changes automatically.
Learn more: [Auth → Session](/docs/extension/auth/session).
</Callout>
## How it works
* **No separate auth flow** in the extension. We reuse the web session.
* **Active organization comes from the session** (e.g., `session.activeOrganizationId`).
* **Protected API calls** from the extension include the right cookies, so org‑scoped server logic works as expected.
![Shared authentication with organizations in extension](/images/docs/extension/organizations.png)
## Active organization
Use your existing auth client to read the active organization through the `useActiveOrganization` hook.
```tsx title="popup.tsx"
import { authClient } from "~/lib/auth";
export function Popup() {
const organization = authClient.useActiveOrganization();
return <>{organization?.name}</>;
}
```
<Callout title="Switching organizations">
If a user switches organizations in the web app, the extension reflects the change through the shared session on the next interaction. For long-lived views, re-read the session or invalidate related queries when appropriate.
</Callout>
## Do more with organizations
Most organization features live in the web app and are exposed via APIs your extension can call. These guides explain the underlying concepts and server behavior your extension builds upon:
<Cards>
<Card title="Overview" description="Concepts and architecture" href="/docs/web/organizations/overview" />
<Card title="Data model" description="Tables and relationships" href="/docs/web/organizations/data-model" />
<Card title="Active organization" description="How organization context is resolved" href="/docs/web/organizations/active-organization" />
<Card title="RBAC" description="Roles and permissions" href="/docs/web/organizations/rbac" />
<Card title="Invitations" description="Invite teammates and manage members" href="/docs/web/organizations/invitations" />
</Cards>
<Callout>
Looking for the underlying auth setup? Start with [Auth →
Overview](/docs/extension/auth/overview) and [Auth →
Session](/docs/extension/auth/session).
</Callout>

162
.context/turbostarter-framework-context/sections/extension/publishing/checklist.md Normal file
View File

@@ -0,0 +1,162 @@
---
title: Checklist
description: Let's publish your TurboStarter extension to stores!
url: /docs/extension/publishing/checklist
---
# Checklist
When you're ready to publish your TurboStarter extension to stores, follow this checklist.
This process may take a few hours and some trial and error, so buckle up - you're almost there!
<Steps>
<Step>
## Create database instance
**Why it's necessary?**
A production-ready database instance is essential for storing your application's data securely and reliably in the cloud. [PostgreSQL](https://www.postgresql.org/) is the recommended database for TurboStarter due to its robustness, features, and wide support.
**How to do it?**
You have several options for hosting your PostgreSQL database:
* [Supabase](/docs/extension/recipes/supabase) - Provides a fully managed Postgres database with additional features
* [Vercel Postgres](https://vercel.com/storage/postgres) - Serverless SQL database optimized for Vercel deployments
* [Neon](https://neon.tech/) - Serverless Postgres with automatic scaling
* [Turso](https://turso.tech/) - Edge database built on libSQL with global replication
* [DigitalOcean](https://www.digitalocean.com/products/managed-databases) - Managed database clusters with automated failover
Choose a provider based on your needs for:
* Pricing and budget
* Geographic region availability
* Scaling requirements
* Additional features (backups, monitoring, etc.)
</Step>
<Step>
## Migrate database
**Why it's necessary?**
Pushing database migrations ensures that your database schema in the remote database instance is configured to match TurboStarter's requirements. This step is crucial for the application to function correctly.
**How to do it?**
You basically have two possibilities for doing a migration:
<Tabs items={["Using GitHub Actions (recommended)", "Running locally"]}>
<Tab value="Using GitHub Actions (recommended)">
TurboStarter comes with a predefined GitHub Action to handle database migrations. You can find its definition in the `.github/workflows/publish-db.yml` file.
What you need to do is set your `DATABASE_URL` as a [secret for your GitHub repository](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).
Then, you can run the workflow which will publish the database schema to your remote database instance.
[Check how to run GitHub Actions workflow.](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow)
</Tab>
<Tab value="Running locally">
You can also run your migrations locally, although this is not recommended for production.
To do so, set the `DATABASE_URL` environment variable to your database URL (that comes from your database provider) in the `.env.local` file and run the following command:
```bash
pnpm with-env pnpm --filter @turbostarter/db db:migrate
```
This command will run the migrations and apply them to your remote database.
[Learn more about database migrations.](/docs/web/database/migrations)
</Tab>
</Tabs>
</Step>
<Step>
## Set up web backend API
**Why it's necessary?**
Setting up the backend is necessary to have a place to store your data and to have other features work properly (e.g. authentication, billing or storage).
**How to do it?**
Please refer to the [web deployment checklist](/docs/web/deployment/checklist) on how to set up and deploy the web app backend to production.
</Step>
<Step>
## Environment variables
**Why it's necessary?**
Setting the correct environment variables is essential for the extension to function correctly. These variables include API keys, database URLs, and other configuration details required for your extension to connect to various services.
**How to do it?**
Use our `.env.example` files to get the correct environment variables for your project. Then add them to your CI/CD provider (e.g. [GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions)) as a [secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).
</Step>
<Step>
## Build your app
**Why it's necessary?**
Building your extension is necessary to create a standalone extension bundle that can be published to the stores.
**How to do it?**
You basically have two possibilities to build a bundle for your extension:
<Tabs items={["Using GitHub Actions (recommended)", "Running locally"]}>
<Tab value="Using GitHub Actions (recommended)">
TurboStarter comes with a predefined GitHub Action to handle building your extension for submission. You can find its definition in the `.github/workflows/publish-extension.yml` file.
[Check how to run GitHub Actions workflow.](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow)
This will also save the `.zip` file as an [artifact](https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts) of the workflow run, so you can download it from there and submit your extension to stores (if configured).
</Tab>
<Tab value="Running locally">
You can also run your build locally, although this is not recommended for production.
To do it, run the following command:
```bash
pnpm turbo build --filter=extension
```
This will build the extension and package it into a `.zip` file. You can find the output in the `build` folder.
</Tab>
</Tabs>
</Step>
<Step>
## Submit to stores
**Why it's necessary?**
Publishing your extension to the stores is required to make it discoverable and accessible to your users. This is the official distribution channel where users can find, install, and trust your extension.
**How to do it?**
We've prepared dedicated guides for each store that TurboStarter supports out-of-the-box, please refer to the following pages:
<Cards>
<Card title="Chrome Web Store" href="/docs/extension/publishing/chrome" description="Publish your extension to Google Chrome Web Store." />
<Card title="Firefox Add-ons" href="/docs/extension/publishing/firefox" description="Publish your extension to Mozilla Firefox Add-ons." />
<Card title="Edge Add-ons" href="/docs/extension/publishing/edge" description="Publish your extension to Microsoft Edge Add-ons." />
</Cards>
</Step>
</Steps>
That's it! Your extension is now live and accessible to your users, good job! 🎉
<Callout title="Other things to consider">
* Optimize your store listing description, keywords, and other relevant information for the stores.
* Remove the placeholder content in the extension or replace it with your own.
* Update the favicon, scheme, store images, and logo with your own branding.
</Callout>

166
.context/turbostarter-framework-context/sections/extension/publishing/chrome.md Normal file
View File

@@ -0,0 +1,166 @@
---
title: Chrome Web Store
description: Publish your extension to Google Chrome Web Store.
url: /docs/extension/publishing/chrome
---
# Chrome Web Store
[Chrome Web Store](https://chromewebstore.google.com/) is the most popular store for browser extensions, as it makes them available in any Chromium-based browser, including Google Chrome, Edge, Brave, and many others.
To submit your extension to Chrome Web Store, you'll need to complete a few steps. Here, we'll go through them.
<Callout title="Prerequisite" type="warn">
Make sure your extension follows the [guidelines](/docs/extension/marketing) and other requirements to increase your chances of getting approved.
</Callout>
## Developer account
Before you can publish items on the Chrome Web Store, you must register as a CWS developer and pay a one-time registration fee. You must provide a developer email when you create your developer account.
To register, just access the [developer console](https://chrome.google.com/webstore/devconsole). The first time you do this, the following registration screen will appear. First, agree to the developer agreement and policies, then pay the registration fee.
![Chrome registration fee](/images/docs/extension/chrome/fee.png)
Once you pay the registration fee and agree to the terms, your account will be created, and you'll be able to proceed to fill out additional information about it.
![Chrome developer account](/images/docs/extension/chrome/account.png)
There are a few fields that you'll need to fill in:
* **Publisher name**: Appears under the title of each of your extensions. If you are a verified publisher, you can display an official publisher URL instead.
* **Verified email**: Verifying your contact email address is required when you set up a new developer account. It's only displayed under your extensions' contact information. Any notifications will be sent to your Chrome Web Store developer account email.
* **Physical address**: Only items that offer functionality to purchase items, additional features, or subscriptions must include a physical address.
<Card title="Register your developer account" href="https://developer.chrome.com/docs/webstore/register" description="developer.chrome.com" />
## Submission
After registering your developer account, setting it up, and preparing your extension, you're ready to publish it to the store.
You can submit your extension in two ways:
* **Manually**: By uploading your extension's bundle directly to the store.
* **Automatically**: By using GitHub Actions to submit your extension to the stores.
**The first submission must be done manually, while subsequent updates can be submitted automatically.** We'll go through both approaches.
### Manual submission
To manually submit your extension to stores, you will first need to get your extension bundle. If you ran the build step locally, you should already have the `.zip` file in your extension's `build` folder.
If you used GitHub Actions to build your extension, you can find the results in the workflow run. Download the artifacts and save them on your local machine.
Then, use the following steps to upload your item:
1. Go to the [Chrome Web Store Developer Dashboard](https://chrome.google.com/webstore/devconsole/).
2. Sign in to your developer account.
3. Click on the *Add new item* button.
4. Click *Choose file* > *your zip file* > *Upload*. If your item's manifest and other contents are valid, you will see a new item in the dashboard.
![Chrome extension page](/images/docs/extension/chrome/extension-page.png)
After you upload the bundle, you'll need to fill in the extension's details, such as the icons, privacy settings, permissions justification, and other information.
Please refer to the official guides on how to set up your extension's details.
<Cards>
<Card title="Complete your listing information" href="https://developer.chrome.com/docs/webstore/cws-dashboard-listing" description="developer.chrome.com" />
<Card title="Fill out the privacy fields" description="developer.chrome.com" href="https://developer.chrome.com/docs/webstore/cws-dashboard-privacy" />
<Card title="Declare payment and set visibility" description="developer.chrome.com" href="https://developer.chrome.com/docs/webstore/cws-dashboard-distribution" />
</Cards>
### Automated submission
<Callout title="First submission must be done manually" type="warn">
The first submission of your extension to Chrome Web Store must be done manually because you need to provide the store's credentials and extension ID to automation, which will be available only after the first bundle upload.
</Callout>
TurboStarter comes with a pre-configured GitHub Actions workflow to submit your extension to web stores automatically. It's located in the `.github/workflows/publish-extension.yml` file.
What you need to do is fill the environment variables with your store's credentials and extension's details and set them as a [secrets in your Github repository](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) under correct names:
```yaml title="publish-extension.yml"
env:
CHROME_EXTENSION_ID: ${{ secrets.CHROME_EXTENSION_ID }}
CHROME_CLIENT_ID: ${{ secrets.CHROME_CLIENT_ID }}
CHROME_CLIENT_SECRET: ${{ secrets.CHROME_CLIENT_SECRET }}
CHROME_REFRESH_TOKEN: ${{ secrets.CHROME_REFRESH_TOKEN }}
```
Please refer to the [official guide](https://github.com/PlasmoHQ/bms/blob/main/tokens.md#chrome-web-store-api) to learn how to get these credentials correctly.
That's it! You can [run the workflow](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow) and it will submit your extension to the Chrome Web Store 🎉
<Callout title="Automated submission to review">
This workflow will also try to send your extension to review, but it's not guaranteed to happen. You need to have all required information filled in your extension's details page to make it possible.
Even then, when you introduce some **breaking change** (e.g. add another permission), you'll need to update your extension store metadata and automatic submit won't be possible.
To opt out of this behavior (and use only automatic uploading to store, but not sending to review) you can set `--chrome-skip-submit-review` flag in the `publish-extension.yml` file for the `wxt submit` command:
```yaml title="publish-extension.yml"
// [!code word:--chrome-skip-submit-review]
- name: 💨 Publish!
run: |
npx wxt submit \
--chrome-zip apps/extension/build/*-chrome.zip --chrome-skip-submit-review
```
Then, your extension bundle will be uploaded to the store, but you will need to send it to review manually.
Check out the [official documentation](https://wxt.dev/api/cli/wxt-submit) for more customization options.
</Callout>
<Cards>
<Card title="Use the Chrome Web Store Publish API" href="https://developer.chrome.com/docs/webstore/using-api" description="developer.chrome.com" />
<Card title="How to generate Google API tokens?" href="https://github.com/PlasmoHQ/chrome-webstore-api/blob/main/token.md" description="github.com" />
</Cards>
## Review
After filling out the information about your item, you are ready to send it to review. Click on *Submit for review* button and confirm that you want to submit your item in the following dialog:
![Chrome submit for review](/images/docs/extension/chrome/send-to-review.png)
The confirmation dialog shown above also lets you control the timing of your item's publishing. If you uncheck the checkbox, your item will **not** be published immediately after its review is complete. Instead, you'll be able to manually publish it at a time of your choosing once the review is complete.
After you submit the item for review, it will undergo a review process. The time for this review depends on the nature of your item. See [Understanding the review process](https://developer.chrome.com/docs/webstore/review-process) for more details.
There are important emails like take down or rejection notifications that are enabled by default. To receive an email notification when your item is published or staged, you can enable notifications on the *Account page*.
![Chrome notifications](/images/docs/extension/chrome/notifications.png)
The review status of your item appears in the [developer dashboard](https://chrome.google.com/webstore/devconsole) next to each item. The status can be one of the following:
* **Published**: Your item is available to all users.
* **Pending**: Your item is under review.
* **Rejected**: Your item was rejected by the store.
* **Taken Down**: Your item was taken down by the store.
![Chrome extension status](/images/docs/extension/chrome/review-status.png)
You'll receive an email notification when the status of your item changes.
<Callout title="Your submission might be rejected" type="error">
If your extension has been determined to violate one or more terms or policies, you will receive an email notification that contains the violation description and instructions on how to rectify it.
If you did not receive an email within a week, check the status of your item. If your item has been rejected, you can see the details on the *Status* tab of your item.
![Chrome extension rejected](/images/docs/extension/chrome/rejection.png)
You'll need to fix the issues and upload a new version of your extension, make sure to follow the [guidelines](/docs/extension/marketing) or check [publishing troubleshooting](/docs/extension/troubleshooting/publishing) for more info.
If you have been informed about a violation and you do not rectify it, your item will be taken down. See [Violation enforcement](https://developer.chrome.com/docs/webstore/review-process#enforcement) for more details.
</Callout>
You can learn more about the review process in the official guides listed below.
<Cards>
<Card title="Chrome Web Store review process" href="https://developer.chrome.com/docs/webstore/review-process" description="developer.chrome.com" />
<Card title="Troubleshooting Chrome Web Store violations" href="https://developer.chrome.com/docs/webstore/troubleshooting" description="developer.chrome.com" />
</Cards>

242
.context/turbostarter-framework-context/sections/extension/publishing/edge.md Normal file
View File

@@ -0,0 +1,242 @@
---
title: Edge Add-ons
description: Publish your extension to Microsoft Edge Add-ons.
url: /docs/extension/publishing/edge
---
# Edge Add-ons
[Microsoft Edge Add-ons](https://microsoftedge.microsoft.com/addons/) distributes extensions to Microsoft Edge users. If you already have a Chromium-based extension, you can submit it to Edge with minimal changes.
This guide walks you through manual submission and optional automation, aligned with the official process.
<Callout title="Prerequisite" type="warn">
Make sure your extension follows the general [guidelines](/docs/extension/marketing) and the Edge Add-ons developer policies to increase your chances of approval.
</Callout>
## Developer account
To enroll in the Microsoft Edge program you need to have a Microsoft account. If you don't have one, you can create one [here](https://account.microsoft.com/account/signup?signin=1\&ru=https://account.microsoft.com/account/login?loginMethod=email).
![Microsoft account](/images/docs/extension/edge/create-microsoft-account.png)
Next, before you can publish your extension to Edge Add-ons, you need to register your developer account in [Partner Center](https://partner.microsoft.com/dashboard/microsoftedge/public/login?ref=dd). Fill out the required fields and submit the form with *Finish* button. Wait for the email that your account has been verified - you're ready to submit your extension!
![Partner Center](/images/docs/extension/edge/developer-account.png)
<Card title="Register as a Microsoft Edge extension developer" href="https://learn.microsoft.com/en-us/microsoft-edge/extensions/publish/create-dev-account" description="learn.microsoft.com" />
## Submission
After your account is ready and the extension bundle is prepared, you can publish it. There are two paths:
* **Manually**: Upload your `.zip` package through Partner Center.
* **Automatically**: Use CI to upload new versions after the first manual submission.
**The first submission should be done manually.** Subsequent updates can be automated once you have your extension ID and required credentials.
### Manual submission
To manually submit your extension to stores, you will first need to get your extension bundle. If you ran the build step locally, you should already have the .zip file in your extension's build folder.
If you used GitHub Actions to build your extension, you can find the results in the workflow run. Download the artifacts and save them on your local machine.
Then, use the following steps to upload your item:
<Steps>
<Step>
#### Sign in to your developer account
Go to the [Partner Center](https://partner.microsoft.com/dashboard/microsoftedge/public/login?ref=dd) and sign in to your developer account.
</Step>
<Step>
#### Create new extension
Click the *Create new extension* button to start a new submission.
![Create new extension](/images/docs/extension/edge/create.png)
</Step>
<Step>
#### Upload the extension package
The *Extension overview* page shows information for a specific extension:
![Extension overview](/images/docs/extension/edge/upload.png)
To upload your extension package:
1. Click *Packages* in the left sidebar.
2. Drag and drop your `.zip` file or click *Browse your files* to select it.
3. Wait for validation to complete. If it fails, fix any issues and re-upload.
4. Review the extracted extension details and click *Continue*.
</Step>
<Step>
#### Set availability
Choose visibility:
* `Public`: discoverable in the store and via search.
* `Hidden`: not discoverable; accessible via direct listing URL only.
Select markets where the extension is available. You can later add or remove markets; existing users retain access to installed versions.
![Availability](/images/docs/extension/edge/availability.png)
</Step>
<Step>
#### Enter properties
Provide category, privacy policy requirements, privacy policy URL (if applicable), website URL, and support contact.
These are shown to users on the listing and must meet policy requirements.
![Properties](/images/docs/extension/edge/properties.png)
Follow the [official documentation](https://learn.microsoft.com/en-us/microsoft-edge/extensions/publish/publish-extension#step-4-enter-properties-describing-your-extension) for more details.
</Step>
<Step>
#### Add store listing details
Fill in the store listing details for your extension:
* **Display name**: The name shown in the store (from your manifest file).
* **Description**: A detailed description (250-5000 characters) explaining what your extension does and why users should install it.
* **Extension Store logo**: A 300x300 pixel logo representing your extension.
* **Screenshots**: Up to 10 screenshots (640x480 or 1280x800 pixels) showing your extension's functionality.
* **Small/Large promotional tiles**: Optional promotional images for store featuring.
* **YouTube video URL**: Optional promotional video.
* **Search terms**: Keywords to help users discover your extension (up to 21 words total).
You must provide the description and logo for each supported language. Other fields are optional but recommended for better discoverability.
![Store listing details](/images/docs/extension/edge/store-listing.png)
Follow the [official documentation](https://learn.microsoft.com/en-us/microsoft-edge/extensions/publish/publish-extension#step-5-add-store-listing-details-for-your-extension) for detailed requirements and best practices.
</Step>
<Step>
#### Submit for review
Complete the submission by providing testing notes to help certification testers understand your extension.
Click the *Submit* button to open the submission page:
![Submit extension](/images/docs/extension/edge/submit.png)
In the **Notes for certification** text box, provide additional information to help testers properly evaluate your extension. Include any relevant details such as:
* Test account usernames and passwords
* Steps to access hidden or locked features
* Expected differences based on region or user settings
* Information about changes if this is an update
* Any other context testers need to understand your submission
Once you've added your notes, click the *Publish* button to submit your extension for certification.
Your extension will proceed to the certification step, which can take up to seven business days.
After passing certification, your extension will be published to [Microsoft Edge Add-ons](https://microsoftedge.microsoft.com/addons/) and the status in Partner Center will change to "In the Store".
</Step>
</Steps>
<Cards>
<Card title="Publish a Microsoft Edge extension" href="https://learn.microsoft.com/en-us/microsoft-edge/extensions/publish/publish-extension" description="learn.microsoft.com" />
<Card title="Curation and review process for extensions at Microsoft Edge Add-ons" href="https://learn.microsoft.com/en-us/microsoft-edge/extensions/publish/add-ons-curation" description="learn.microsoft.com" />
</Cards>
## Automated submission
<Callout title="First submission must be done manually" type="warn">
The first submission of your extension to Microsoft Edge Add-ons must be done manually because you need to provide the store's credentials and extension ID to automation, which will be available only after the first bundle upload.
</Callout>
TurboStarter comes with a pre-configured GitHub Actions workflow to submit your extension to web stores automatically. It's located in the .github/workflows/publish-extension.yml file.
What you need to do is fill the environment variables with your store's credentials and extension's details and set them as a [secrets in your Github repository](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) under correct names:
```yaml title="publish-extension.yml"
env:
EDGE_PRODUCT_ID: ${{ secrets.EDGE_PRODUCT_ID }}
EDGE_CLIENT_ID: ${{ secrets.EDGE_CLIENT_ID }}
EDGE_API_KEY: ${{ secrets.EDGE_API_KEY }}
```
Please refer to the [official guide](https://github.com/PlasmoHQ/bms/blob/main/tokens.md#edge-add-ons-api-v11) to learn how to get these credentials correctly.
Once configured, you can manually [trigger the workflow](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow) to upload the new version to Edge Add-ons 🎉
<Callout title="Automated submission to review">
This workflow will also try to send your extension to review, but it's not guaranteed to happen. You need to have all required information filled in your extension's details page to make it possible.
Even then, when you introduce some **breaking change** (e.g. add another permission), you'll need to update your extension store metadata and automatic submit won't be possible.
To opt out of this behavior (and use only automatic uploading to store, but not sending to review) you can set `--edge-skip-submit-review` flag in the `publish-extension.yml` file for the `wxt submit` command:
```yaml title="publish-extension.yml"
// [!code word:--edge-skip-submit-review]
- name: 💨 Publish!
run: |
npx wxt submit \
--edge-zip apps/extension/build/*-chrome.zip --edge-skip-submit-review
```
Then, your extension bundle will be uploaded to the store, but you will need to send it to review manually.
Check out the [official documentation](https://wxt.dev/api/cli/wxt-submit) for more customization options.
</Callout>
<Cards>
<Card title="Alternative ways to distribute an extension" href="https://learn.microsoft.com/en-us/microsoft-edge/extensions/developer-guide/alternate-distribution-options" description="learn.microsoft.com" />
<Card title="REST API for updating an extension" href="https://learn.microsoft.com/en-us/microsoft-edge/extensions/update/api/using-addons-api?tabs=v1-1" description="learn.microsoft.com" />
</Cards>
## Review
After you submit your extension, it enters Microsoft's certification and publishing pipeline.
1. Preprocessing
* Uploaded packages are queued and scanned. If errors are detected during preprocessing, you'll see a message and must resolve issues before re-uploading.
2. Certification
* Security tests: packages are checked for viruses and malware.
* Content compliance: human review of your listing and content for policy adherence.
3. Release and publishing
* If you selected publish immediately, publishing begins right away; otherwise schedule/hold options apply.
* While publishing, the submission status page shows rollout details. When complete, the status changes from "Publishing" to "In the Store".
4. Edge Add-ons curation and ranking
* Discovery is influenced by quality, relevancy (name, description, popularity, user experience), and popularity (ratings and averages). Security and policy compliance are verified per the developer policies.
Microsoft may also perform spot checks after publishing to ensure ongoing compliance.
The review status of your item appears in the [Partner Center](https://partner.microsoft.com/dashboard/microsoftedge/public/login?ref=dd) under the *Overview* page of your item.
![Edge extension review status](/images/docs/extension/edge/review-status.png)
You'll receive an email notification when the status of your item changes.
<Callout title="Your submission might be rejected" type="error">
If your extension has been determined to violate one or more terms or policies, you will receive an email notification that contains the violation description and instructions on how to rectify it.
![Rejection email](/images/docs/extension/edge/rejection-email.png)
You can also check the reason behind the rejection on the *Certification report* page of your item.
![Certification report](/images/docs/extension/edge/certification-report.png)
You'll need to fix the issues and upload a new version of your extension. Make sure to follow the [guidelines](/docs/extension/marketing) or check [publishing troubleshooting](/docs/extension/troubleshooting/publishing) for more info.
</Callout>
You can learn more about the review process in the official guides listed below.
<Cards>
<Card title="Microsoft Edge Add-ons developer policies" href="https://learn.microsoft.com/en-us/legal/microsoft-edge/extensions/developer-policies" description="learn.microsoft.com" />
<Card title="The app certification process for add-on" href="https://learn.microsoft.com/en-us/windows/apps/publish/publish-your-app/add-on/app-certification-process" description="learn.microsoft.com" />
<Card title="Curation and review process for extensions at Microsoft Edge Add-ons" href="https://learn.microsoft.com/en-us/microsoft-edge/extensions/publish/add-ons-curation" description="learn.microsoft.com" />
</Cards>

218
.context/turbostarter-framework-context/sections/extension/publishing/firefox.md Normal file
View File

@@ -0,0 +1,218 @@
---
title: Firefox Add-ons
description: Publish your extension to Mozilla Firefox Add-ons.
url: /docs/extension/publishing/firefox
---
# Firefox Add-ons
Mozilla Firefox doesn't share extensions with [Google Chrome](/docs/extension/publishing/chrome), so you'll need to publish your extension to it separately.
Here, we'll go through the process of publishing an extension to [Firefox Add-ons](https://addons.mozilla.org/).
<Callout title="Prerequisite" type="warn">
Make sure your extension follows the [guidelines](/docs/extension/marketing) and other requirements to increase your chances of getting approved.
</Callout>
## Developer account
Before you can publish items on Firefox Add-ons, you must register a developer account. In comparison to the Chrome Web Store, Firefox Add-ons doesn't require a registration fee.
To register, go to [addons.mozilla.org](https://addons.mozilla.org/) and click on the *Register* button.
![Mozilla registration](/images/docs/extension/firefox/portal.png)
It's important to set at least a display name on your profile to increase transparency with users, add-on reviewers, and the greater community.
You can do it in the *Edit My Profile* section:
![Mozilla profile](/images/docs/extension/firefox/profile.png)
<Card title="Developer accounts" href="https://extensionworkshop.com/documentation/publish/developer-accounts/" description="extensionworkshop.com" />
## Submission
After registering your developer account, setting it up, and preparing your extension, you're ready to publish it to the store.
You can submit your extension in two ways:
* **Manually**: By uploading your extension's bundle directly to the store.
* **Automatically**: By using GitHub Actions to submit your extension to the stores.
**The first submission must be done manually, while subsequent updates can be submitted automatically.** We'll go through both approaches.
### Manual submission
To manually submit your extension to stores, you will first need to get your extension bundle. If you ran the build step locally, you should already have the `.zip` file in your extension's `build` folder.
If you used GitHub Actions to build your extension, you can find the results in the workflow run. Download the artifacts and save them on your local machine.
Then, use the following steps to upload your item:
<Steps>
<Step>
#### Sign in to your developer account
Go to the [Add-ons Developer Hub](https://addons.mozilla.org/developers/) and sign in to your developer account.
</Step>
<Step>
#### Choose distribution method
You should reach the following page:
![Mozilla distribution](/images/docs/extension/firefox/distribution.png)
Here, you have two ways of distributing your extension:
* **On this site**, if you want your add-on listed on AMO (Add-ons Manager).
* **On your own**, if you plan to distribute the add-on yourself and don't want it listed on AMO.
We recommend going with the first option, as it will allow you to reach more users and get more feedback. If you decide to go with the second option, please refer to the [official documentation](https://extensionworkshop.com/documentation/publish/self-distribution/) for more details.
</Step>
<Step>
#### Submit your extension
On the next page, click on *Select file* and choose your extension's `.zip` bundle.
![Mozilla upload](/images/docs/extension/firefox/upload.png)
Once you upload the bundle, the validator checks the add-on for issues and the page updates:
![Mozilla validation](/images/docs/extension/firefox/validation.png)
If your add-on passes all the checks, you can proceed to the next step.
<Callout type="warn">
You may receive a message that you only have warnings. It's advisable to address these warnings, particularly those flagged as security or privacy issues, as they may result in your add-on failing review. However, **you can continue with the submission**.
</Callout>
If the validation fails, you'll need to address the issues and upload a new version of your add-on.
</Step>
<Step>
#### Submit source code (if needed)
You'll need to indicate whether you need to provide the source code of your extension:
![Mozilla source code](/images/docs/extension/firefox/source-code.png)
If you select *Yes*, a section displays describing what you need to submit. Click *Browse* and locate and upload your source code package. See [Source code submission](https://extensionworkshop.com/documentation/publish/source-code-submission/) for more information.
<Callout type="warn">
You may receive a message that you only have warnings. It's advisable to address these warnings, particularly those flagged as security or privacy issues, as they may result in your add-on failing review. However, **you can continue with the submission**.
</Callout>
If the validation fails, you'll need to address the issues and upload a new version of your add-on.
</Step>
<Step>
#### Add metadata
On the next page, you'll need to provide the following additional information about your extension:
![Mozilla additional information](/images/docs/extension/firefox/additional-info.png)
* **Name**: Your add-on's name.
* **Add-on URL**: The URL for your add-on on AMO. A URL is automatically assigned based on your add-on's name. To change this, click Edit. The URL must be unique. You will be warned if another add-on is using your chosen URL, and you must enter a different one.
* **Summary**: A useful and descriptive short summary of your add-on.
* **Description**: A longer description that provides users with details of the extension's features and functionality.
* **This add-on is experimental**: Indicate if your add-on is experimental or otherwise not ready for general use. The add-on will be listed but with reduced visibility. You can remove this flag when your add-on is ready for general use.
* **This add-on requires payment, non-free services or software, or additional hardware**: Indicate if your add-on requires users to make an additional purchase for it to work fully.
* **Select up to 2 Firefox categories for this add-on**: Select categories that describe your add-on.
* **Select up to 2 Firefox for Android categories for this add-on**: Select categories that describe your add-on.
* **Support email and Support website**: Provide an email address and website where users can get in touch when they have questions, issues, or compliments.
* **License**: Select the appropriate license for your add-on. Click Details to learn more about each license.
* **This add-on has a privacy policy**: If any data is being transmitted from the user's device, a privacy policy explaining what is being sent and how it's used is required. Check this box and provide the privacy policy.
* **Notes for Reviewers**: Provide information to assist the AMO reviewer, such as login details for a dummy account, source code information, or similar.
</Step>
<Step>
#### Finalize the process
Once you're ready, click on the *Submit Version* button.
![Mozilla submit](/images/docs/extension/firefox/submit.png)
You can still edit your add-on's details from the dedicated page after submission.
</Step>
</Steps>
<Cards>
<Card title="Resources for publishers" href="https://extensionworkshop.com/documentation/manage/resources-for-publishers/" description="extensionworkshop.com" />
<Card title="Source code submission" href="https://extensionworkshop.com/documentation/publish/source-code-submission/" description="extensionworkshop.com" />
</Cards>
### Automated submission
<Callout title="First submission must be done manually" type="warn">
The first submission of your extension to Firefox Add-ons must be done manually because you need to provide the store's credentials and extension ID to automation, which will be available only after the first bundle upload.
</Callout>
TurboStarter comes with a pre-configured GitHub Actions workflow to submit your extension to web stores automatically. It's located in the `.github/workflows/publish-extension.yml` file.
What you need to do is fill the environment variables with your store's credentials and extension's details and set them as a [secrets in your Github repository](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) under correct names:
```yaml title="publish-extension.yml"
env:
FIREFOX_EXTENSION_ID: ${{ secrets.FIREFOX_EXTENSION_ID }}
FIREFOX_JWT_ISSUER: ${{ secrets.FIREFOX_JWT_ISSUER }}
FIREFOX_JWT_SECRET: ${{ secrets.FIREFOX_JWT_SECRET }}
```
Please refer to the [official guide](https://github.com/PlasmoHQ/bms/blob/main/tokens.md#firefox-add-ons-api) to learn how to get these credentials correctly.
That's it! You can [run the workflow](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow) and it will submit your extension to the Firefox Add-ons 🎉
<Callout title="Automated submission to review">
This workflow will also try to send your extension to review, but it's not guaranteed to happen. You need to have all required information filled in your extension's details page to make it possible.
Even then, when you introduce some **breaking change** (e.g., add another permission), you'll need to update your extension store metadata and automatic submission won't be possible.
</Callout>
<Cards>
<Card title="A new API for submitting and updating add-ons" href="https://blog.mozilla.org/addons/2022/03/17/new-api-for-submitting-and-updating-add-ons/" description="blog.mozilla.org" />
<Card title="Mozilla API keys" href="https://addons.mozilla.org/en-US/developers/addon/api/key/" description="addons.mozilla.org" />
</Cards>
## Review
Once you submit your extension bundle, it's automatically sent to review and will undergo a review process. The time for this review depends on the nature of your item.
The add-on review process includes the following phases:
1. **Automatic Review**: Upon upload, the add-on undergoes several automatic validation steps to ensure its general safety.
2. **Content Review**: Shortly after submission, a human reviewer inspects the add-on to ensure that the listing adheres to content review guidelines, including metadata such as the add-on name and description.
3. **Technical Code Review**: The add-on's source code is examined to ensure compliance with review policies.
4. **Basic Functionality Testing**: After the source code is verified as safe, the add-on undergoes basic functionality testing to confirm it operates as described.
There are important emails like takedown or rejection notifications that are enabled by default. To receive an email notification when your item is published or staged, you can enable notifications in the *Account Settings*.
![Mozilla notifications](/images/docs/extension/firefox/notifications.png)
The review status of your item appears in the [developer hub](https://addons.mozilla.org/en-US/firefox/) next to each item.
![Mozilla review status](/images/docs/extension/firefox/review-status.png)
You'll receive an email notification when the status of your item changes.
<Callout title="Your submission might be rejected" type="error">
If your extension has been determined to violate one or more terms or policies, you will receive an email notification that contains the violation description and instructions on how to rectify it.
You can also check the reason behind the rejection on the *Status* page of your item.
![Mozilla extension rejected](/images/docs/extension/firefox/rejection.png)
You'll need to fix the issues and upload a new version of your extension. Make sure to follow the [guidelines](/docs/extension/marketing) or check [publishing troubleshooting](/docs/extension/troubleshooting/publishing) for more info.
</Callout>
You can learn more about the review process in the official guides listed below.
<Cards>
<Card title="Add-ons/Reviewers/Guide/Reviewing" href="https://wiki.mozilla.org/Add-ons/Reviewers/Guide/Reviewing" description="wiki.mozilla.org" />
<Card title="Add-ons/Reviewers/Content Review Guidelines" href="https://wiki.mozilla.org/Add-ons/Reviewers/Content_Review_Guidelines" description="wiki.mozilla.org" />
</Cards>

28
.context/turbostarter-framework-context/sections/extension/publishing/updates.md Normal file
View File

@@ -0,0 +1,28 @@
---
title: Updates
description: Learn how to update your published extension.
url: /docs/extension/publishing/updates
---
# Updates
After publishing your extension to the stores, you can release updates to deliver new features and bug fixes to your users.
TurboStarter provides a ready-to-use process for updating your extensions. Let's quickly review how it works.
## Uploading a new version
The recommended way to update your extension is to submit a new version to the stores. This method is the most reliable, although it may take some time for the new version to be approved and become available to users.
To submit a new version, simply update the version number in your `package.json` file:
```json title="package.json"
{
...
"version": "1.0.0", // [!code --]
"version": "1.0.1", // [!code ++]
...
}
```
Next, follow the exact same steps as [when you initially published your extension](/docs/extension/publishing/checklist). When submitting your extension for review, be sure to provide release notes describing the new version.

221
.context/turbostarter-framework-context/sections/extension/recipes/supabase.md Normal file
View File

@@ -0,0 +1,221 @@
---
title: Supabase
description: Learn how to set up Supabase as the database (and optional storage) provider for your TurboStarter project.
url: /docs/extension/recipes/supabase
---
# Supabase
[Supabase](https://supabase.com) is an open-source backend platform built on top of PostgreSQL that provides a managed database, storage, and other features out of the box.
You can adopt Supabase incrementally - start with just the pieces you need (for example, database only, or database + storage) and add more features over time. There's no requirement to integrate everything at once.
In this guide, we'll walk you through the process of setting up Supabase as a provider for your TurboStarter project. This could include using it as a [database](https://supabase.com/docs/guides/database), [storage](https://supabase.com/docs/guides/storage), [edge runtime for your API](https://supabase.com/docs/guides/functions) and more.
## Prerequisites
Before you start, make sure you have:
* **TurboStarter project** cloned locally with dependencies installed (you can use our [CLI](/docs/web/cli) to create a new project in seconds)
* **Supabase account** - you can create one at [supabase.com](https://supabase.com/sign-up)
* Basic familiarity with the core database docs:
* [Database overview](/docs/web/database/overview)
* [Migrations](/docs/web/database/migrations)
* [Database client](/docs/web/database/client)
<Steps>
<Step>
## Create a new Supabase project
1. Go to the [Supabase dashboard](https://supabase.com).
2. Create a **new project** (choose a strong database password and a region close to your users).
3. Supabase will automatically provision a **PostgreSQL database** for you.
![Create a new Supabase project](/images/docs/web/recipes/supabase/create-project.png)
Optionally, you can customize the **Security options** by choosing the **Only Connection String** option - it will opt out of autogenerating API for tables inside your database. It's not needed for TurboStarter setup, but of course you can still leverage it for your custom use-cases.
![Security options](/images/docs/web/recipes/supabase/security-options.png)
Once the project is ready, you can fetch the connection string.
</Step>
<Step>
## Get the database connection string
In the Supabase dashboard:
1. Open your project.
2. Click on the **Connect** button at the top.
3. Locate the **connection string** for your chosen ORM (it will be under the **ORMs** tab).
![Connect application](/images/docs/web/recipes/supabase/connect-app.png)
Copy this value - you'll use it as your `DATABASE_URL`.
<Callout title="Replace password placeholder" type="warn">
In your Supabase connection string, you can see a placeholder like `[YOUR-PASSWORD]`. Make sure to replace this with the actual password you set when creating your Supabase project.
</Callout>
</Step>
<Step>
## Configure environment variables
TurboStarter reads database connection settings from the **root** `.env.local` file and uses them inside the `@turbostarter/db` package.
Create (or update) the `.env.local` file in the **monorepo root**:
```dotenv title=".env.local"
DATABASE_URL="postgres://postgres.[YOUR-PROJECT-REF]:[YOUR-PASSWORD]@aws-0-[aws-region].pooler.supabase.com:6543/postgres?pgbouncer=true&connection_limit=1"
```
Replace:
* `YOUR-PROJECT-REF` with your Supabase project ref
* `YOUR-PASSWORD` with the database password you set when creating the project
* `aws-region` with the region shown in the Supabase connection string
<Callout>
These variables are validated in the `@turbostarter/db` package and used to create Drizzle client for your database.
</Callout>
For more background on how `DATABASE_URL` is used, see [Database overview](/docs/web/database/overview).
</Step>
<Step>
## Setup your Supabase database
With `DATABASE_URL` now pointing to Supabase, you can apply the existing TurboStarter schema to your Supabase database.
From the monorepo root, run:
```bash
pnpm with-env pnpm --filter @turbostarter/db db:migrate
```
This will:
* Use your Supabase `DATABASE_URL` from `.env.local`
* Run all pending SQL migrations from `packages/db/migrations`
* Create the full TurboStarter schema (users, billing, demo tables, etc.) in Supabase
If you're actively iterating on the schema, you can generate new migrations and apply them as described in [Migrations](/docs/web/database/migrations).
<Callout title="Seeding your database" type="info">
After running your migrations, you may want to seed your database with initial data (such as demo users or organizations). You can do this by running the following command:
```bash
pnpm with-env pnpm turbo db:seed
```
This will populate your Supabase database with some example data you can use to test your application.
</Callout>
</Step>
<Step>
## Use Supabase Storage as S3-compatible storage
TurboStarter's storage layer is designed to work seamlessly with **any S3-compatible provider**. In this section, we'll show how to use [Supabase Storage](/docs/web/storage/overview) as your application's file storage back-end.
Supabase Storage provides a simple, S3-compatible API and is a great choice if you're already using Supabase for your database.
### Create a storage bucket
1. In the Supabase dashboard, go to **Storage → Buckets**.
2. Click **Create bucket** (name it whatever you want, for example `avatars` or `uploads`).
3. Adjust settings based on your needs (e.g. limit the maximum file size, specify the allowed file types, etc.)
![Create a new bucket](/images/docs/web/recipes/supabase/create-bucket.png)
You can create multiple buckets (for documents, images, videos, etc.) if needed.
### Generate S3 access keys in Supabase dashboard
1. Go to **Storage → S3 → Access keys**.
2. Click **New access key**.
3. Give it a descriptive name and create the key.
4. Copy the **Access key ID** and **Secret access key** to use in your application.
![Generate S3 access keys](/images/docs/web/recipes/supabase/s3-keys.png)
### Configure S3 environment variables for Supabase Storage
In your weba application's `.env.local`, add (or update) the S3 configuration used by TurboStarter's storage layer:
```dotenv title=".env.local"
S3_REGION="us-east-1"
S3_BUCKET="avatars"
S3_ENDPOINT="https://[YOUR-PROJECT-REF].supabase.co/storage/v1/s3"
S3_ACCESS_KEY_ID="your-access-key-id"
S3_SECRET_ACCESS_KEY="your-secret-access-key"
```
These variables integrate directly with the storage configuration described in:
* [Storage overview](/docs/web/storage/overview)
* [Storage configuration](/docs/web/storage/configuration)
Once set, existing TurboStarter file upload flows (e.g. user avatars, organization logos) will use Supabase Storage via presigned URLs.
</Step>
<Step>
## Run your API on Supabase Edge Functions
As we're using a [Hono](https://hono.dev) as our API server, you can deploy it as a Supabase Edge Function so it runs close to your users.
At a high level:
1. Install the [Supabase CLI](https://supabase.com/docs/guides/cli) and initialize a Supabase project locally with `supabase init`.
2. Create a new [Edge Function](https://supabase.com/docs/guides/functions/quickstart) (for example `hono-backend`) with `supabase functions new hono-backend`.
3. Inside the generated function (for example `supabase/functions/hono-backend/index.ts`), set up a basic Hono app and export it via `Deno.serve(app.fetch)`:
```ts
import { Hono } from "jsr:@hono/hono";
// change this to your function name
const functionName = "hono-backend";
const app = new Hono().basePath(`/${functionName}`);
app.get("/hello", (c) => c.text("Hello from hono-server!"));
Deno.serve(app.fetch);
```
4. Run the function locally with `supabase start` and `supabase functions serve --no-verify-jwt`, then call it from your TurboStarter app using the local or deployed function URL.
5. When you're ready, deploy the function with `supabase functions deploy` (or `supabase functions deploy hono-backend`) and manage it using the Supabase dashboard, as described in the [Supabase Edge Functions docs](https://supabase.com/docs/guides/functions).
This is entirely optional, but it's a great fit for lightweight APIs, webhooks, and other serverless logic you want to run alongside your Supabase project.
</Step>
<Step>
## Explore additional Supabase features
Supabase is a full Postgres development platform, so beyond the database and storage pieces wired up above you can gradually add more features as your app grows ([see the Supabase homepage](https://supabase.com/) for an overview).
Some features that fit especially well with TurboStarter's design are:
* [Realtime](https://supabase.com/docs/guides/realtime) - built on [Postgres replication](https://www.postgresql.org/docs/current/runtime-config-replication.html), so you can stream changes from your existing TurboStarter tables (inserts, updates, deletes) into live UIs without changing how you manage schema or RLS. You still define tables and policies via `@turbostarter/db`, and opt into Realtime on top.
* [Vector](https://supabase.com/docs/guides/vector) - powered by the [pgvector](https://github.com/pgvector/pgvector) extension and stored in regular Postgres tables, making it easy to integrate semantic search or AI features while keeping everything in the same migrations and Drizzle models you already use in TurboStarter. We're using it extensively in our dedicated [AI Kit](/ai).
* [Cron](https://supabase.com/docs/guides/functions/cron) - enables you to schedule background jobs and periodic tasks with [pg\_cron](https://github.com/citusdata/pg_cron). You can define cron jobs for things like scheduled database cleanups, sending emails, report generation, or any recurring logic, all managed alongside your TurboStarter app with full Postgres integration.
Because these features are all layered on top of Postgres, you can introduce them incrementally and keep managing everything through your familiar workflow.
</Step>
<Step>
## Start the development server
With the database and other services configured to use Supabase, you can start TurboStarter as usual from the monorepo root:
```bash
pnpm dev
```
TurboStarter will now:
* Use **Supabase Postgres** as your database through `DATABASE_URL`
* Use **Supabase Storage** as your file storage through the S3-compatible endpoint
* Leverage **Supabase Edge Functions** (for example, with Hono) for your serverless backend
</Step>
</Steps>
That's it! You can now start building your application with Supabase as your main provider. Explore the [Supabase documentation](https://supabase.com/docs) for more features and best practices.

82
.context/turbostarter-framework-context/sections/extension/stack.md Normal file
View File

@@ -0,0 +1,82 @@
---
title: Tech Stack
description: A detailed look at the technical details.
url: /docs/extension/stack
---
# Tech Stack
## Turborepo
[Turborepo](https://turbo.build/) is a monorepo tool that helps you manage your project's dependencies and scripts. We chose a monorepo setup to make it easier to manage the structure of different features and enable code sharing between different packages.
<Card href="https://turbo.build/" title="Turborepo - Make Ship Happen" description="turbo.build" icon={<Turborepo />} />
## WXT (Vite)
> It's like Next.js for browser extensions.
[WXT](https://www.wxt.dev/) is a very lightweight and powerful framework (based on [Vite](https://vite.dev/)) for building browser extensions using most popular frontend tools. It provides a modern development experience with features like hot module reloading, TypeScript support, and automatic manifest generation.
WXT simplifies the process of creating cross-browser extensions, allowing you to focus on your extension's functionality rather than boilerplate setup.
<Cards>
<Card href="https://www.wxt.dev/" title="WXT" description="wxt.dev" icon={<Wxt />} />
<Card href="https://www.vite.dev/" title="Vite" description="vite.dev" icon={<Vite />} />
</Cards>
## React
[React](https://reactjs.org/) is a JavaScript library for building user interfaces. It's the core technology we use for creating the UI of our browser extension, allowing for efficient updates and rendering of components.
<Card href="https://reactjs.org/" title="React" description="reactjs.org" icon={<React />} />
## Tailwind CSS
[Tailwind CSS](https://tailwindcss.com) is a utility-first CSS framework that helps you build custom designs without writing any CSS. We also use [Radix UI](https://radix-ui.com) for our headless components library and [shadcn/ui](https://ui.shadcn.com) which enables you to generate pre-designed components with a single command.
<Cards className="grid-cols-2 sm:grid-cols-3">
<Card href="https://tailwindcss.com" title="Tailwind CSS" description="tailwindcss.com" icon={<Tailwind />} />
<Card href="https://radix-ui.com" title="Radix UI" description="radix-ui.com" icon={<Radix />} />
<Card href="https://ui.shadcn.com" title="shadcn/ui" description="ui.shadcn.com" icon={<Shadcn />} />
</Cards>
## Hono & React Query
[Hono](https://hono.dev) is a small, simple, and ultrafast web framework for the edge. It provides tools to help you build APIs and web applications faster. It includes an RPC client for making type-safe function calls from the frontend. We use Hono to build our serverless API endpoints.
To make data fetching and caching from our API easy and reliable, we pair Hono with [React Query](https://tanstack.com/query/latest). It helps manage asynchronous data, caching, and state synchronization between the client and backend, delivering a fast and seamless UX.
<Cards>
<Card href="https://hono.dev" title="Hono" description="hono.dev" icon={<Hono />} />
<Card
href="https://tanstack.com/query/latest"
title="React Query"
description="tanstack.com"
icon={
<img src="/images/icons/tanstack.png" alt="" width={32} height={32} />
}
/>
</Cards>
## Better Auth
[Better Auth](https://www.better-auth.com) is a modern authentication library for fullstack applications. It provides ready-to-use snippets for features like email/password login, magic links, OAuth providers, and more. We use Better Auth to handle all authentication flows in our application.
<Card href="https://www.better-auth.com" title="Better Auth" description="better-auth.com" icon={<BetterAuth />} />
## Drizzle
[Drizzle](https://orm.drizzle.team/) is a super fast [ORM](https://orm.drizzle.team/docs/overview) (Object-Relational Mapping) tool for databases. It helps manage databases, generate TypeScript types from your schema, and run queries in a fully type-safe way.
We use [PostgreSQL](https://www.postgresql.org) as our default database, but thanks to Drizzle's flexibility, you can easily switch to MySQL, SQLite or any [other supported database](https://orm.drizzle.team/docs/connect-overview) by updating a few configuration lines.
<Cards>
<Card href="https://orm.drizzle.team/" title="Drizzle" description="orm.drizzle.team" icon={<Drizzle />} />
<Card href="https://www.postgresql.org" title="PostgreSQL" description="postgresql.org" icon={<Postgres />} />
</Cards>

63
.context/turbostarter-framework-context/sections/extension/structure/background.md Normal file
View File

@@ -0,0 +1,63 @@
---
title: Background service worker
description: Configure your extension's background service worker.
url: /docs/extension/structure/background
---
# Background service worker
An extension's service worker is a powerful script that runs in the background, separate from other parts of the extension. It's loaded when it is needed, and unloaded when it goes dormant.
Once loaded, an extension service worker generally runs as long as it is actively receiving events, though it [can shut down](https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/lifecycle#idle-shutdown). Like its web counterpart, an extension service worker cannot access the DOM, though you can use it if needed with [offscreen documents](https://developer.chrome.com/docs/extensions/reference/api/offscreen).
Extension service workers are more than network proxies (as web service workers are often described), they run in a separate [service worker context](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers). For example, when in this context, you no longer need to worry about CORS and can fetch resources from any origin.
In addition to the [standard service worker events](https://developer.mozilla.org/docs/Web/API/ServiceWorkerGlobalScope#events), they also respond to extension events such as navigating to a new page, clicking a notification, or closing a tab. They're also registered and updated differently from web service workers.
**It's common to offload heavy computation to the background service worker**, so you should always try to do resouce-expensive operations there and send results using [Messages API](/docs/extension/structure/messaging) to other parts of the extension.
Code for the background service worker is located at `src/app/background` directory - you need to use `defineBackground` within `index.ts` file inside to allow WXT to include your script in the build.
```ts title="src/app/background/index.ts"
import { defineBackground } from "wxt/sandbox";
const main = () => {
console.log(
"Background service worker is running! Edit `src/app/background` and save to reload.",
);
};
export default defineBackground(main);
```
To see the service worker in action, reload the extension, then open its "Service Worker inspector":
![Service Worker inspector](/images/docs/extension/structure/sw-inspector.png)
You should see what we've logged in the console:
![Service Worker console](/images/docs/extension/structure/sw-log.png)
To communicate with the service worker from other parts of the extension, you can use the [Messaging API](/docs/extension/structure/messaging).
## Persisting state
<Callout>
Service workers in `dev` mode always remain in `active` state.
</Callout>
The worker becomes idle after a few seconds of inactivity, and the browser will kill its process entirely after 5 minutes. This means all state (variables, etc.) is lost unless you use a storage engine.
The simplest way to persist your background service worker's state is to use the [storage API](/docs/extension/structure/storage).
The more advanced way is to send the state to a remote database via our [backend API](/docs/extension/api/overview).
<Cards>
<Card title="Using service workers" href="https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers" description="developer.mozilla.org" />
<Card title="Migrate to a service worker" href="https://developer.chrome.com/docs/extensions/develop/migrate/to-service-workers" description="developer.chrome.com" />
<Card title="Extension service worker basics" href="https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/basics" description="developer.chrome.com" />
<Card title="The extension service worker lifecycle" href="https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/lifecycle" description="developer.chrome.com" />
</Cards>

94
.context/turbostarter-framework-context/sections/extension/structure/content-scripts.md Normal file
View File

@@ -0,0 +1,94 @@
---
title: Content scripts
description: Learn more about content scripts.
url: /docs/extension/structure/content-scripts
---
# Content scripts
Content scripts run in the context of web pages in an isolated world. This allows multiple content scripts from various extensions to coexist without conflicting with each other's execution and to stay isolated from the page's JavaScript.
A script that ends with `.ts` will not have front-end runtime (e.g. react) bundled with it and won't be treated as a ui script, while a script that ends in `.tsx` will be.
There are many use cases for content scripts:
* Injecting a custom stylesheet into the page
* Scraping data from the current web page
* Selecting, finding, and styling elements from the current web page
* Injecting UI elements into current web page
Code for the content scripts is located in `src/app/content` directory - you need to define `.ts` or `.tsx` file inside and use `defineContentScript` to allow WXT to include your script in the build.
```ts title="src/app/content/index.ts"
export default defineContentScript({
matches: ["<all_urls>"],
async main(ctx) {
console.log(
"Content script is running! Edit `app/content` and save to reload.",
);
},
});
```
Reload your extension, open a web page, then open its inspector:
![Content Script](/images/docs/extension/structure/content-script.png)
To learn more about content scripts, e.g. how to configure only specific pages to load content scripts, how to inject them into `window` object or how to fetch data inside, please check [the official documentation](https://wxt.dev/guide/essentials/content-scripts.html).
## UI scripts
WXT has first-class support for mounting React components into the current webpage. This feature is called content scripts UI (CSUI).
![CSUI](/images/docs/extension/structure/csui.png)
An extension can have as many CSUI as needed, with each CSUI targeting a group of webpages or a specific webpage.
To get started with CSUI, create a `.tsx` file in `src/app/content` directory and use `defineContentScript` allow WXT to include your script in the build and mount your component into the current webpage:
```tsx title="src/app/content/index.tsx"
const ContentScriptUI = () => {
return (
<Button onClick={() => alert("This is injected UI!")}>
Content script UI
</Button>
);
};
export default defineContentScript({
matches: ["<all_urls>"],
cssInjectionMode: "ui",
async main(ctx) {
const ui = await createShadowRootUi(ctx, {
name: "turbostarter-extension",
position: "overlay",
anchor: "body",
onMount: (container) => {
const app = document.createElement("div");
container.append(app);
const root = ReactDOM.createRoot(app);
root.render(<ContentScriptUI />);
return root;
},
onRemove: (root) => {
root?.unmount();
},
});
ui.mount();
},
});
export default ContentScriptUI;
```
<Callout title="File extensions matters!" type="warn">
The `.tsx` extension is essential to differentiate between Content Scripts UI and regular Content Scripts. Make sure to check if you're using appropriate type of content script for your use case.
</Callout>
To learn more about content scripts UI, e.g. how to inject custom styles, fonts or the whole lifecycle of a component, please check [the official documentation](https://wxt.dev/guide/essentials/content-scripts.html#ui).
<Callout title="How does it work?">
Under the hood, the component is wrapped inside the component that implements the Shadow DOM technique, together with many helpful features. This isolation technique prevents the web page's style from affecting your component's styling and vice-versa.
[Read more about the lifecycle of CSUI](https://docs.plasmo.com/framework/content-scripts-ui/life-cycle)
</Callout>

95
.context/turbostarter-framework-context/sections/extension/structure/messaging.md Normal file
View File

@@ -0,0 +1,95 @@
---
title: Messaging
description: Communicate between your extension's components.
url: /docs/extension/structure/messaging
---
# Messaging
Messaging API makes communication between different parts of your extension easy. To make it simple and scalable, we're leveraging `@webext-core/messaging` library.
It provides a declarative, type-safe, functional, promise-based API for sending, relaying, and receiving messages between your extension components.
## Handling messages
Based on our convention, we implemented a little abstraction on top of `@webext-core/messaging` to make it easier to use. That's why all types and keys are stored inside `lib/messaging` directory:
```ts title="lib/messaging/index.ts"
import { defineExtensionMessaging } from "@webext-core/messaging";
export const Message = {
HELLO: "hello",
} as const;
export type Message = (typeof Message)[keyof typeof Message];
interface Messages {
[Message.HELLO]: (message: string) => string;
}
export const { onMessage, sendMessage } = defineExtensionMessaging<Messages>();
```
There you need to define what will be handled under each key. To make it more secure, only `Message` enum and `onMessage` and `sendMessage` functions are exported from the module.
All message handlers are located in `src/app/background/messaging` directory under respective subdirectories.
To create a message handler, create a TypeScript module in the `background/messaging` directory. Then, include your handlers for all keys related to the message:
```ts title="app/background/messaging/hello.ts"
import { onMessage, Message } from "~/lib/messaging";
onMessage(Message.HELLO, (req) => {
const result = await querySomeApi(req.body.id);
return result;
});
```
<Callout title="Don't forget to import!" type="warn">
To make your handlers available across your extension, you need to import them
in the `background/index.ts` file. That way they could be interpreted by the
build process facilitated by WXT.
</Callout>
## Sending messages
Extension pages, content scripts, or tab pages can send messages to the handlers using the `sendMessage` function. Since we orchestrate your handlers behind the scenes, the message names are typed and will enable autocompletion in your editor:
```tsx title="app/popup/index.tsx"
import { sendMessage, Message } from "~/lib/messaging";
...
const response = await sendMessage(Message.HELLO, "Hello, world!");
console.log(response);
...
```
As it's an asynchronous operation, it's advisable to use [@tanstack/react-query](https://tanstack.com/query/latest/docs/framework/react/overview) integration to handle the response on the client side.
We're already doing it that way when fetching auth session in the `User` component:
```tsx title="hello.tsx"
export const Hello = () => {
const { data, isLoading } = useQuery({
queryKey: [Message.HELLO],
queryFn: () => sendMessage(Message.HELLO, "Hello, world!"),
});
if (isLoading) {
return <p>Loading...</p>;
}
/* do something with the data... */
return <p>{data?.message}</p>;
};
```
<Cards>
<Card href="https://webext-core.aklinker1.io/messaging/installation/" title="Messaging API" description="webext-core.aklinker1.io" />
<Card title="Message passing" description="developer.chrome.com" href="https://developer.chrome.com/docs/extensions/develop/concepts/messaging" />
</Cards>

50
.context/turbostarter-framework-context/sections/extension/structure/overview.md Normal file
View File

@@ -0,0 +1,50 @@
---
title: Overview
description: Learn about the structure of the extension app.
url: /docs/extension/structure/overview
---
# Overview
Every browser extension is different and can include different parts, removing the ones that are not needed.
TurboStarter ships with all the things you need to start developing your own extension including:
* **Popup window** - a small window that appears when the user clicks the extension icon.
* **Options page** - a page that appears when user enters extension settings.
* **Side panel** - a panel that appears when the user clicks sidepanel.
* **New tab page** - a page that appears when the user opens a new tab.
* **Devtools page** - a page that appears when the user opens the browser's devtools.
* **Tab pages** - custom pages shipped with the extension.
* **Content scripts** - injected scripts that run in the browser page.
* **Background scripts** - scripts that run in the background.
* **Message passing** - a way to communicate between different parts of the extension.
* **Storage** - a way to store data in the extension.
All the entrypoints are defined in `apps/extension/src/app` directory (it's similar to file-based routing in Next.js and Expo).
This directory acts as a source for WXT framework which is used to build the extension. It has the following structure:
<Files>
<Folder name="app" defaultOpen>
<Folder name="background - Background service worker" />
<Folder name="content - Content scripts" />
<Folder name="devtools - Devtools page with custom panels" />
<Folder name="newtab - New tab page" />
<Folder name="options - Options page" />
<Folder name="popup - Popup window" />
<Folder name="sidepanel - Side panel" />
<Folder name="tabs - Custom pages shipped with the extension" />
</Folder>
</Files>
By structurizing it this way, we can easily add new entrypoints in the future and extend rest of the extension independently from each other.
We'll go through each part and explain the purpose of it, check following sections for more details:

77
.context/turbostarter-framework-context/sections/extension/structure/pages.md Normal file
View File

@@ -0,0 +1,77 @@
---
title: Pages
description: Get started with your extension's pages.
url: /docs/extension/structure/pages
---
# Pages
Extension pages are built-in pages recognized by the browser. They include the extension's popup, options, sidepanel and newtab pages.
<Callout>
As WXT is based on Vite, it has very powerful [HMR support](https://vite.dev/guide/features#hot-module-replacement). This means that you don't need to refresh the extension manually when you make changes to the code.
</Callout>
## Popup
The popup page is a small dialog window that opens when a user clicks on the extension's icon in the browser toolbar. It is the most common type of extension page.
![Popup window](/images/docs/extension/structure/popup.png)
<Cards>
<Card title="Add a popup" href="https://developer.chrome.com/docs/extensions/develop/ui/add-popup" description="developer.chrome.com" />
<Card title="Entrypoints" href="https://wxt.dev/guide/essentials/entrypoints.html" description="wxt.dev" />
</Cards>
## Options
The options page is meant to be a dedicated place for the extension's settings and configuration.
![Options page](/images/docs/extension/structure/options.png)
<Card title="Give users options" href="https://developer.chrome.com/docs/extensions/develop/ui/options-page" description="developer.chrome.com" />
## Devtools
The devtools page is a custom page (including panels) that opens when a user opens the extension's devtools panel.
![Devtools page](/images/docs/extension/structure/devtools.png)
<Card title="Extend devtools" href="https://developer.chrome.com/docs/extensions/how-to/devtools/extend-devtools" description="developer.chrome.com" />
## New tab
The new tab page is a custom page that opens when a user opens a new tab in the browser.
![New tab page](/images/docs/extension/structure/newtab.png)
<Card title="Override Chrome pages" href="https://developer.chrome.com/docs/extensions/develop/ui/override-chrome-pages" description="developer.chrome.com" />
## Side panel
The side panel is a custom page that opens when a user clicks on the extension's icon in the browser toolbar.
![Side panel](/images/docs/extension/structure/sidepanel.png)
<Card title="Side panel" href="https://developer.chrome.com/docs/extensions/reference/api/sidePanel" description="developer.chrome.com" />
## Tabs
Unlike traditional extension pages, tab (unlisted) pages are just regular web pages shipped with your extension bundle. Extensions generally redirect to or open these pages programmatically, but you can link to them as well.
They could be useful for following cases:
* when you want to show a some page when user first installs your extension
* when you want to have dedicated pages for authentication
* when you need more advanced routing setup
![Tab page](/images/docs/extension/structure/tabs.png)
Your tab page will be available under the `/tabs` path in the extension bundle. It will be accessible from the browser under the URL:
```
chrome-extension://<your-extension-id>/tabs/your-tab-page.html
```
<Card title="Unlisted pages" href="https://wxt.dev/guide/essentials/entrypoints.html#unlisted-pages" description="wxt.dev" />

109
.context/turbostarter-framework-context/sections/extension/structure/storage.md Normal file
View File

@@ -0,0 +1,109 @@
---
title: Storage
description: Learn how to store data in your extension.
url: /docs/extension/structure/storage
---
# Storage
TurboStarter leverages `wxt/storage` library to handle persistent storage for your extension. It's a utility library from that abstracts the persistent storage API available to browser extensions.
It falls back to localStorage when the extension storage API is unavailable, allowing for state sync between extension pages, content scripts, background service workers and web pages.
<Callout>
To use the `wxt/storage` API, the "storage" permission **must** be added to the manifest:
```ts title="wxt.config.ts"
export default defineConfig({
manifest: {
permissions: ["storage"],
},
});
```
</Callout>
## Storing data
The base Storage API is designed to be easy to use. It is usable in every extension runtime such as background service workers, content scripts and extension pages.
TurboStarter ships with predefined storage used to handle [theming](/docs/extension/customization/styling) in your extension, but you can create your own storage as well.
All storage-related methods and types are located in `lib/storage` directory.
```ts title="lib/storage/index.ts"
export const StorageKey = {
THEME: "local:theme",
} as const;
export type StorageKey = (typeof StorageKey)[keyof typeof StorageKey];
```
Then, to make it available around your extension, we're setting it up and providing default values:
```ts title="lib/storage/index.ts"
import { storage as browserStorage } from "wxt/storage";
import { appConfig } from "~/config/app";
import type { ThemeConfig } from "@turbostarter/ui";
const storage = {
[StorageKey.THEME]: browserStorage.defineItem<ThemeConfig>(StorageKey.THEME, {
fallback: appConfig.theme,
}),
} as const;
```
To learn more about customizing your storage, syncing state or setup automatic backups please refer to the [official documentation](https://wxt.dev/storage.html).
## Consuming storage
To consume storage in your extension, you can use the `useStorage` React hook that is automatically provided to every part of the extension. The hook API is designed to streamline the state-syncing workflow between the different pieces of an extension.
Here is an example on how to consume our theme storage in `Layout` component:
```tsx title="modules/common/layout/layout.tsx"
import { StorageKey, useStorage } from "~/lib/storage";
export const Layout = ({ children }: { children: React.ReactNode }) => {
const { data } = useStorage(StorageKey.THEME);
return (
<div id="root" data-theme={data.color}>
{children}
</div>
);
};
```
Congrats! You've just learned how to persist and consume global data in your extension 🎉
For more advanced use cases, please refer to the [official documentation](https://wxt.dev/storage.html).
### Usage with Firefox
To use the storage API on Firefox during development you need to add an addon ID to your manifest, otherwise, you will get this error:
> Error: The storage API will not work with a temporary addon ID. Please add an explicit addon ID to your manifest. For more information see [https://mzl.la/3lPk1aE](https://mzl.la/3lPk1aE)
To add an addon ID to your manifest, add this to your package.json:
```ts title="wxt.config.ts"
export default defineConfig({
manifest: {
browser_specific_settings: {
gecko: {
id: "your-id@example.com",
},
},
},
});
```
During development, you may use any ID. If you have published your extension, you need to use the ID assigned by [Firefox Add-ons](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons).
<Cards>
<Card title="Storage API" href="https://wxt.dev/storage.html" description="wxt.dev" />
<Card title="chrome.storage" href="https://developer.chrome.com/docs/extensions/reference/api/storage" description="developer.chrome.com" />
</Cards>

15
.context/turbostarter-framework-context/sections/extension/tests/e2e.md Normal file
View File

@@ -0,0 +1,15 @@
---
title: E2E tests
description: Simulate real user scenarios across the entire stack with automated end-to-end test tools and examples.
url: /docs/extension/tests/e2e
---
# E2E tests
<Callout title="E2E testing is coming soon">
End-to-end (E2E) tests will be available soon, allowing you to automate testing of real user flows and interactions across your application.
Stay tuned for updates as we roll out robust E2E testing resources and examples.
[See roadmap](https://github.com/orgs/turbostarter/projects/1)
</Callout>

136
.context/turbostarter-framework-context/sections/extension/tests/unit.md Normal file
View File

@@ -0,0 +1,136 @@
---
title: Unit tests
description: Write and run fast unit tests for individual functions and components with instant feedback.
url: /docs/extension/tests/unit
---
# Unit tests
Unit tests are a type of automated test where individual units or components are tested. The "unit" in "unit test" refers to the smallest testable parts of an application. These tests are designed to verify that each unit of code performs as expected.
TurboStarter uses [Vitest](https://vitest.dev) as the unit testing framework. It's a blazing-fast test runner built on top of [Vite](https://vitejs.dev), designed for modern JavaScript and TypeScript projects.
<Callout title="Why Vitest?">
If you've used [Jest](https://jestjs.io) before, you already know Vitest - it shares the same API. But Vitest is built for speed: native TypeScript support without transpilation, parallel test execution, and a smart watch mode that only re-runs tests affected by your changes.
It comes with everything you need out of the box - code coverage, snapshot testing, mocking, and a slick UI for debugging. Fast feedback, zero configuration.
</Callout>
## Why write unit tests?
Unit tests give you **fast, focused feedback** on small pieces of your code - individual functions, hooks, or components. Instead of debugging an entire page or flow, you can verify just the logic you care about in isolation.
They also act as **living documentation**: a good test tells you how a function is supposed to behave, which edge cases are important, and what assumptions the code makes. This makes it much easier to safely refactor or extend features later.
In TurboStarter, unit tests are designed to be **cheap and quick to run**, so you can keep Vitest running in watch mode while you code. Every change you make is immediately checked, helping you catch regressions before they ever reach integration or end‑to‑end tests.
## Configuration
TurboStarter configures Vitest to be **as simple as possible**, while still taking advantage of [Turborepo's caching](https://turborepo.com/docs/crafting-your-repository/caching) and Vitest's [Test Projects](https://vitest.dev/guide/projects).
```ts title="vitest.config.ts"
import { mergeConfig } from "vitest/config";
import baseConfig from "@turbostarter/vitest-config/base";
export default mergeConfig(baseConfig, {
test: {
/* your extended test configuration here */
},
});
```
* **Per-package tests**: each package that has unit tests defines its own `test` script. This keeps the configuration close to the code and makes it easy to add tests to any workspace.
* **Turbo tasks for CI**: the root `test` task (`pnpm test`) uses `turbo run test` to execute all package-level test scripts with smart caching, which is ideal for CI pipelines where you want to avoid re-running unchanged tests.
* **Vitest Test Projects for local dev**: a root Vitest configuration uses [Test Projects](https://vitest.dev/guide/projects) to run all unit test suites from a single command, which is perfect for local development when you want fast feedback across the whole monorepo.
This **hybrid setup** combines Turborepo and Vitest Projects in a way that fits TurboStarter's principles: cached, package-aware runs in CI, and a single, unified Vitest entry point for local development.
You can read more about this setup in the official documentation guides listed below.
<Cards>
<Card title="Vitest" description="turborepo.com" href="https://turborepo.com/docs/guides/tools/vitest" />
<Card title="Test Projects" description="vitest.dev" href="https://vitest.dev/guide/projects" />
</Cards>
## Running tests
There are a few different ways to run unit tests, depending on what you're doing:
* **CI / full test run** - at the root of the repo:
```bash
pnpm test
```
This runs `turbo run test`, which executes all `test` scripts in packages that define them, with Turborepo handling caching so unchanged packages are skipped. This is what you should use in your CI/CD pipeline.
* **One-off local run with Vitest Projects**:
```bash
pnpm test:projects
```
This uses Vitest [Test Projects](https://vitest.dev/guide/projects) to run all configured unit test suites from a single command, which is great when you want to quickly validate the whole monorepo locally.
* **Watch mode during development**:
```bash
pnpm test:projects:watch
```
This starts Vitest in watch mode across all Test Projects. As you edit files, only the affected tests are re-run, giving you fast feedback while you work.
## Code coverage
Unit test coverage helps you understand **how much** of your code is being tested. While it can't guarantee bug-free code, it shines a light on untested paths that could hide issues or regressions.
To generate a code coverage report for all unit tests, run:
```bash
pnpm turbo test:coverage
```
This command runs the coverage task across all relevant packages (using Turborepo) and collects the results into a single coverage output.
To open the coverage report in your browser:
```bash
pnpm turbo test:coverage:view
```
This will build the HTML report and launch it using your default browser, so you can explore which files and branches are covered.
<Callout title="Uploading coverage as an artifact">
You can also store the generated coverage report as a [GitHub Actions artifact](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts) during your CI/CD pipeline, just add the following steps to your workflow job:
```yaml title=".github/workflows/ci.yml"
# your workflow job configuration here
- name: 📊 Generate coverage
run: pnpm turbo test:coverage
- name: 🗃️ Archive coverage report
uses: actions/upload-artifact@v5
with:
name: coverage-${{ github.sha }}
path: tooling/vitest/coverage/report
```
This will generate a test coverage report and upload it as an artifact, so you can access it from GitHub Actions tab for later inspection.
</Callout>
A high coverage percentage means your tests execute most lines and branches - but the quality and relevance of your tests matter more than the raw number. Use coverage reports to spot gaps and guide improvements, not as the sole metric of test health.
![Code coverage](/images/docs/code-coverage.png)
## Best practices
Unit tests should work **for you**, not the other way around. Focus on writing tests that make it easier to change code with confidence, not on satisfying arbitrary rules or reaching a magic number in a dashboard.
Code coverage is a **useful metric**, but it **SHOULD NOT** be the goal. It's better to have a smaller set of high‑value tests that cover critical paths and edge cases than a huge suite of fragile tests that are hard to maintain.
When in doubt, ask: *“Does this test give **me** confidence that I can change this code without breaking users?”* If the answer is no, refactor or remove it.
Finally, keep unit tests focused on **small, isolated pieces of logic**. More advanced flows — like multi-step user journeys, cross-service interactions, or full-page behavior — are better covered by [end-to-end (E2E) tests](/docs/web/tests/e2e), where you can verify the system as a whole.

79
.context/turbostarter-framework-context/sections/extension/troubleshooting/installation.md Normal file
View File

@@ -0,0 +1,79 @@
---
title: Installation
description: Find answers to common extension installation issues.
url: /docs/extension/troubleshooting/installation
---
# Installation
## 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 TurboStarter, and the locally connected account are the same.
## Local database doesn't start
If you cannot run the local database container, it's likely you have not started [Docker](https://docs.docker.com/get-docker/) locally. Our local database requires Docker to be installed and running.
Please make sure you have installed Docker (or compatible software such as [Colima](https://github.com/abiosoft/colima), [Orbstack](https://github.com/orbstack/orbstack)) and that is running on your local machine.
Also, make sure that you have enough [memory and CPU allocated](https://docs.docker.com/engine/containers/resource_constraints/) to your Docker instance.
## Permissions issues
If some feature of your extension is not working, it's possible that you're missing a permission in the manifest config.
Make sure to check the [permissions](/docs/extension/configuration/manifest#overriding-manifest) section in the manifest config file.
## I don't see my translations
If you don't see your translations appearing in the application, there are a few common causes:
1. Check that your translation `.json` files are properly formatted and located in the correct directory
2. Verify that the language codes in your configuration match your translation files
3. Enable debug mode (`debug: true`) in your i18next configuration to see detailed logs
[Read more about configuration for translations](/docs/extension/internationalization#configuration)
## "Module not found" error
This issue is mostly related to either dependency installed in the wrong package or issues with the file system.
The most common cause is incorrect dependency installation. Here's how to fix it:
1. Clean the workspace:
```bash
pnpm clean
```
2. Reinstall the dependencies:
```bash
pnpm i
```
If you're adding new dependencies, make sure to install them in the correct package:
```bash
# For main app dependencies
pnpm install --filter mobile my-package
# For a specific package
pnpm install --filter @turbostarter/ui my-package
```
If the issue persists, please check the file system for any issues.
### Windows OneDrive
OneDrive can cause file system issues with Node.js projects due to its file syncing behavior. If you're using Windows with OneDrive, you have two options to resolve this:
1. Move your project to a location outside of OneDrive-synced folders (recommended)
2. Disable OneDrive sync specifically for your development folder
This prevents file watching and symlink issues that can occur when OneDrive tries to sync Node.js project files.

62
.context/turbostarter-framework-context/sections/extension/troubleshooting/publishing.md Normal file
View File

@@ -0,0 +1,62 @@
---
title: Publishing
description: Find answers to common publishing issues.
url: /docs/extension/troubleshooting/publishing
---
# Publishing
## My extension submission was rejected
If your extension submission was rejected, you probably got an email with the reason. You'll need to fix the issues and upload a new build of your extension to the store and send it for review again.
Make sure to follow the [guidelines](/docs/extension/marketing) when submitting your extension to ensure that everything is setup correctly.
## Version number mismatch
If you get version number conflicts when submitting:
1. Ensure your `manifest.json` version matches what's in the store
2. Increment the version number appropriately for each new submission
3. Make sure the version follows semantic versioning (e.g., `1.0.1`)
## Missing permissions in manifest
If your extension is rejected due to permission issues:
1. Review the permissions declared in your `manifest.json`
2. Ensure all permissions are properly justified in your submission
3. Remove any unused permissions that aren't essential
4. Consider using optional permissions where possible
[Learn more about permissions](/docs/extension/configuration/manifest#permissions)
## Content Security Policy (CSP) violations
If your extension is rejected due to CSP issues:
1. Check your manifest's `content_security_policy` field
2. Ensure all external resources are properly whitelisted
3. Remove any unsafe inline scripts or eval usage
4. Use more secure alternatives like `browser.scripting.executeScript`
## My extension crashes on production build
If the extension works during development but crashes after publishing or when loaded unpacked in production mode, check these common causes:
1. **Uncaught runtime errors** in the background service worker or content scripts. Open `chrome://extensions` (or `about:debugging` in Firefox) → enable Developer mode → Inspect the service worker/content script and check the console for stack traces.
2. **Missing permissions or host permissions** causing APIs to throw (e.g., network calls, tabs access). Ensure required `permissions` and `host_permissions` are declared in `manifest.json`.
3. **CSP blocking resources** (inline scripts/styles, remote fonts, or endpoints). Verify `content_security_policy` and update code to avoid unsafe patterns.
4. **Missing assets or incorrect paths** referenced in `manifest.json` (`icons`, `web_accessible_resources`, `action.default_popup`, etc.). Confirm files exist in the final build output and paths match.
5. **Build-time variables not resolved**. If you rely on environment variables, ensure they’re inlined at build time or have safe fallbacks at runtime. Example:
```js
const apiUrl = env.VITE_SITE_URL ?? "https://api.example.com";
```
6. **Module format or bundler config issues** (MV3 service worker must be ESM if `type: 'module'`). Align bundler output with your manifest expectations and rebuild.
Try this:
1. Reproduce with a production bundle locally and load it as an unpacked extension; inspect background and content script logs for errors.
2. Validate `manifest.json` and ensure all referenced files are present in the build output.
3. Temporarily relax CSP locally to confirm whether CSP is the cause; then apply a compliant fix (don’t ship relaxed CSP).
4. Add fallbacks for any build-time variables and rebuild.