{/* ... */}
)
}
```
## Costs
When using the [Cloudflare Monorepo](/docs/picking-a-template/cloudflare-monorepo) template, pluv.io will run on your own [Durable Objects](https://www.cloudflare.com/developer-platform/products/durable-objects/) instances, which are free to use with extremely generous free tier limits.
When using the [Vercel Monorepo](/docs/picking-a-template/vercel-monorepo) template, pluv.io will run on [pluv.io's](https://pluv.io) servers, which have much more limited free tier limits, then cost $29/month.
## Setup
Setting up pluv.io is relatively simple, but depends on the template you are using.
### Cloudflare Monorepo
1. In the `realtime` app, add an environment variable for `PLUV_AUTH_SECRET` to your `.dev.vars` file.
* This secret will be used to generate securely-signed JWT tokens for your users.
```txt title="/apps/realtime/.dev.vars"
PLUV_AUTH_SECRET="your-secret-key"
```
2. In the `web` app, add an environment variable for `NEXT_PUBLIC_REALTIME_ORIGIN_URL` to your `.env` file.
* This should be the origin URL of your realtime app. For example, if you deployed your realtime app to `https://realtime.your-app.com`, you would add the following environment variable:
```txt title="/apps/web/.env"
NEXT_PUBLIC_REALTIME_ORIGIN_URL="https://realtime.your-app.com"
```
### Vercel Monorepo
1. Create an account on [pluv.io](https://pluv.io) and create a new project.
2. Go to the API Keys page and create a new API key. You can find this page by clicking on the "API Keys" link in the left sidebar.
3. Create an API secret key, and store both the "Publishable Key" and "Secret Key" values to your `.env` file.
```txt title="/apps/web/.env"
NEXT_PUBLIC_PLUV_PUBLISHABLE_KEY="your-publishable-key-here"
PLUV_SECRET_KEY="your-secret-key"
```
## Removal
You may not need to add real-time collaboration to your app. [ship.pluv.io](https://ship.pluv.io) has been built so that if you don't need it, removal of the real-time features is as simple as deleting some API routes and removing a React provider.
To remove pluv.io from the app, perform the following steps:
1. Disconnect the `rooms` route from your app's API routes.
```ts title="/apps/web/src/app/api/[[...route]]/route.ts"
const app = new Hono<{ Bindings: CloudflareEnv }>()
.basePath("/api")
.use(cors)
// ...
// Remove the `/rooms` route below
.route("/rooms", router.rooms);
```
2. Remove the `PluvRoomProvider` from your project page's layout, located in `/apps/web/src/app/(app)/[teamSlug]/[projectSlug]layout.tsx`.
```tsx title="/apps/web/src/app/(app)/[teamSlug]/[projectSlug]layout.tsx"
// ...
const Layout: FC-
{groceries.map((grocery) => (
- {grocery} ))}
{teams.isPending &&
);
};
export default Page;
```
### Mutating in React
```tsx title="page.tsx"
"use client";
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { rpc } from "@/lib/rpc";
import type { InferRequestType } from "hono";
import type { FC } from "react";
interface PageProps {
params: Promise<{ teamSlug: string }>;
}
const Page: FCLoading...
} {teams.isError &&Error: {teams.error.message}
} {teams.isSuccess && (-
{teams.data.map((team) => (
- {team.name} ))}
{/* ... */}
;
};
```
## TypeScript performance
TypeScript performance is a common concern when using heavily type-inferred libraries. Hono RPC is no exception. As you define more endpoints, you may notice a slowdown in your IDE's performance, particularly with intellisense and type checking.
When working within the `@workspace-apps/web` app, all of your types should be automatically inferred between the backend and frontend; however, you can run `pnpm hono:generate` to statically generate the types for your endpoints. Once you run this command, the generated RPC with flat types will be made available in `/apps/web/hono/rpc`.
You can continue using the rpc with fully inferred types, but if you find that your IDE is starting to struggle with performance, you can switch to rpc with flat types by importing from the generated rpc instead.
```bash title="/apps/web"
pnpm hono:generate
```
```tsx title="page.tsx"
// rpc with generated flat types
// this is extremely performant, but requires you to run `pnpm hono:generate`
import { rpc } from "@/hono/rpc";
// rpc with fully inferred types
// this may show down your Next.js dev server and IDE performance,
// but it does not require you to run `pnpm hono:generate`
import { rpc } from "@/lib/rpc";
```
## Why not tRPC?
[tRPC](https://trpc.io/) is a fantastic library for building type-safe APIs in TypeScript, and there are no reasons why you shouldn't use it if you enjoy its API. However, there are a few reasons why we chose to use Hono RPC instead.
### Built on Web Standards
Hono RPC is built on top of [Web Standards](https://hono.dev/docs/concepts/web-standard), notably the Fetch API, and includes basic HTTP primitives like Request, Response, URL and Headers.
Building on top of these standards makes it easier to follow tutorials and documentation that are based on these standards, and makes it more interoperable with other libraries and tools in the JavaScript and web ecosystems.
### Type Safety
Like tRPC, Hono RPC allows you to share types between your client and server, ensuring that your API calls are type-safe end-to-end.
```ts twoslash title="example.ts"
import { zValidator as zv } from "@hono/zod-validator";
import { Hono } from "hono";
import { hc } from "hono/client";
import { z } from "zod";
// server
const app = new Hono().basePath("/api").post(
"/teams",
zv("json", z.object({ name: z.string() })),
(c) => {
const { name } = c.req.valid("json");
const created = { id: "123", name };
return c.json({ team: created }, 200);
},
);
// client
const rpc = hc
](https://www.npmjs.com/package/@trpc/server) | [
](https://www.npmjs.com/package/hono) |
| GitHub | [https://github.com/trpc/trpc](https://github.com/trpc/trpc) | [https://github.com/honojs/hono](https://github.com/honojs/hono) |
| Built on Web Standards | 🪄 No. Abstracts away standard APIs | 🛠️ Yes. Builds around standard APIs |
| End-to-end type-safety | 🛡️ Yes | 🛡️ Yes |
| IDE-performant at scale | 🐌 No | ⚡ Yes, when using flat types. Else no |
| Can build flat types | 🛑 No. At least would be very difficult | ✅ Yes. Can simply use tsc |
| Can cmd+click to server | 🖱️ Yes. Goes straight to the procedure | 🔎 No. Must search for the endpoint in code |
| Works with React Query | ✅ Yes | ✅ Yes |
| Client/Server coupling | 🔗 Tightly coupled | 🌱 Uncoupled. Can be in different repos and different languages |
| Routing model | Procedure-based | HTTP verb and path-based |
# SEO
URL: /docs/features/seo
SEO utilities to make sure your page is represented correctly and ranks on Google
## Utility functions
[ship.pluv.io](https://ship.pluv.io) comes with several utility functions to ensure each of your pages have the relevant SEO tags and data to be represented correctly and ranked on search engines.
### getSeoMetadata
The `getSeoMetadata` function defines a central location where your site-wide defaults for SEO metadata can be configured. The default values for this function are defined within the following config file: `/packages/configs/defaultSeoMetadata.js`.
```tsx title="page.tsx"
import { getSeoMetadata } from "@workspace/utils";
import type { Metadata } from "next";
// As a value
export const metadata: Metadata = getSeoMetadata({
// You can provide properties to overwrite the defaults
title: "My custom title",
description: "My custom description",
});
// If you need to dynamically generate metadata, export `generateMetadata`
// instead, and provide a function parameter to getSeoMetadata
export const generateMetadata = getSeoMetadata(async () => {
const details = await getMyMetadataDetails(/* ... */);
return {
// You can provide properties to overwrite the defaults
title: details.title,
description: "My custom description",
};
});
```
#### Tips
* Next.js will [automatically merge metadata](https://nextjs.org/docs/app/api-reference/functions/generate-metadata#merging) objects shallowly for a given route. So often times, you should only need to call `getSeoMetadata` in each Next.js app's root layout. Then for all other pages/layouts, you can just export the metadata partial object containing the fields you wish to overwrite.
### JsonLd
Type-safe SEO rich snippets via the `JsonLd` component. This component can represent either a single entity or a graph containing multiple entities.
Once the `@type` property is provided, TypeScript will infer the correct attributes for that entity so you can provide the other properties of those entities confidently.
Render this in your page component wherever you wish to provide this.
```tsx title="page.tsx"
import { JsonLd } from "@workspace/ui/custom/JsonLd";
// As a single entity
{/* ... */}
<>
);
}
```
#### Tips
* If you are building an application that supports user reviews for products, consider adding `JsonLd` to those product pages and include star ratings. These will appear on Google, and can make users more likely to visit your site.
### OG image generation
OG image generation is included via the [@vercel/og](https://vercel.com/docs/og-image-generation) package. OG images are generated dynamically via the `/api/og` route. Provide a custom `title` and `description` property to generate the image. The route can be called as a typesafe function via the [rpc](/features/rpc).
The included OG image template can be updated within the following component file: `/packages/og-images/src/templates/OgGlobalTemplate`.
```tsx title="page.tsx"
import { rpc } from "@/shared/rpc";
import type { Metadata } from "next";
const ogImage: URL = rpc.api.og.$url({
query: {
title: "How to Make Hard-Boiled Eggs",
description: "Delicious recipes",
},
});
// Next.js metadata export
export const metadata: Metadata = {
// ... other metadata
openGraph: {
// ... other openGraph data
images: [ogImage],
},
};
```
### Sitemap generation
Sitemaps and robots.txt files are automatically generated for each Next.js app zone via the [next-sitemap](https://www.npmjs.com/package/next-sitemap) package each time your app is built (i.e. during automated deployments with your hosting provider).
Each Next.js app zone's sitemaps will be correctly indexed and linked together, even when deployed separately. If you wish to configure your sitemap generation, edit the `next-sitemap.config.js` files at the base of each Next.js app directory.
## Blog
SEO metadata will be taken from the `SEO Title` and `Meta Description` columns automatically from your Notion database. All other properties will be taken from the `metadata` exported from the `marketing` root layout. See the [Blog](/doccs/features/pages/blog) documentation for more details.
## Docs
SEO metadata will be taken from your [page's frontmatter](https://fumadocs.dev/docs/ui/page-conventions#file) title and description properties. All other properties will be taken from the `metadata` exported from the `docs` root layout.
# UI
URL: /docs/features/ui
Learn about installing shadcn/ui compnents and how to use type-safe icons.
[ship.pluv.io](https://ship.pluv.io) templates are built with [shadcn/ui](https://ui.shadcn.com/), allowing you to quickly install components that you can customize to your liking.
## Installing shadcn/ui components
You can install shadcn/ui components by installing them with the [shadcn/ui CLI](https://ui.shadcn.com/docs/cli).
1. Navigate to the `/packages/ui` directory.
2. Find a component you want to install (e.g. [https://ui.shadcn.com/docs/components/checkbox](https://ui.shadcn.com/docs/components/checkbox))
3. Run the CLI installation command
```bash title="/packages/ui"
pnpm dlx shadcn@latest add checkbox
```
This package already has the shadcn/ui CLI installed, so you can choose to run the following command instead:
```bash title="/packages/ui"
pnpm shadcn add checkbox
```
## Using type-safe icons
There are 2 ways to use type-safe icons in your project:
### Using lucide-react
```tsx title="page.tsx"
import { RocketIcon } from "lucide-react";