Backend as a Service Stubs (withastro#3101)

Co-authored-by: Alex <[email protected]>
Co-authored-by: Yan Thomas <[email protected]>
Co-authored-by: Sarah Rainsberger <[email protected]>
Co-authored-by: Kevin Zuniga Cuellar <[email protected]>

src/components/BackendGuidesNav.astro

@@ -0,0 +1,57 @@
+---
+import { englishPages } from '~/content';
+import { isBackendEntry } from '~/content/config';
+import { isLogoKey } from '~/data/logos';
+import { getLanguageFromURL } from '../util';
+import CardsNav from './NavGrid/CardsNav.astro';
+
+const lang = getLanguageFromURL(Astro.url.pathname);
+const enPages = englishPages.filter(isBackendEntry);
+
+/** Array of services we have good content for and want to show first in the list. */
+const showFirst = ['Firebase'];
+// Reverse the array to make our logic simpler later.
+showFirst.reverse();
+
+const links = enPages
+	.sort((a, b) => {
+		// Sort services in the `showFirst` array first.
+		const aPriority = showFirst.indexOf(a.data.service);
+		const bPriority = showFirst.indexOf(b.data.service);
+		if (aPriority !== -1 || bPriority !== -1) return aPriority > bPriority ? -1 : 1;
+		// Sort full guides before stubs.
+		if (a.data.stub && !b.data.stub) return 1;
+		if (!a.data.stub && b.data.stub) return -1;
+		// If they’re both stubs, or neither stubs, sort alphabetically.
+		return a.data.service.toLowerCase() > b.data.service.toLowerCase() ? 1 : -1;
+	})
+	.map((page) => {
+		const { service } = page.data;
+		const pageUrl = '/' + page.slug.replace('en/', `${lang}/`) + '/';
+		const logo = isLogoKey(page.slug.split('/').pop());
+		return { title: service, href: pageUrl, logo };
+	});
+---
+
+<section class="backend-nav">
+	<CardsNav minimal links={links} />
+</section>
+
+<style>
+	.backend-nav > :global(*) {
+		margin-top: -2rem;
+	}
+
+	.backend-nav > :global(* + *) {
+		margin-top: -3rem;
+	}
+
+	.backend-nav :global(.scope) {
+		font-weight: normal;
+		color: var(--theme-text-lighter);
+	}
+
+	h3 {
+		margin-bottom: 0;
+	}
+</style>

src/content/config.ts

@@ -15,6 +15,12 @@ export const deploySchema = baseSchema.extend({
 	type: z.literal('deploy'),
 });
 
+export const backendSchema = baseSchema.extend({
+	type: z.literal('backend'),
+	stub: z.boolean().default(false),
+	service: z.string(),
+});
+
 export const cmsSchema = baseSchema.extend({
 	type: z.literal('cms'),
 	stub: z.boolean().default(false),
@@ -54,6 +60,10 @@ export type DeployEntry = CollectionEntry<'docs'> & {
 	data: z.infer<typeof deploySchema>;
 };
 
+export type BackendEntry = CollectionEntry<'docs'> & {
+	data: z.infer<typeof backendSchema>;
+};
+
 export type CmsEntry = CollectionEntry<'docs'> & {
 	data: z.infer<typeof cmsSchema>;
 };
@@ -76,6 +86,10 @@ export type RecipeEntry = CollectionEntry<'docs'> & {
 
 export type IntegrationCategory = z.infer<typeof integrationSchema>['category'];
 
+export function isBackendEntry(entry: CollectionEntry<'docs'>): entry is BackendEntry {
+	return entry.data.type === 'backend';
+}
+
 export function isCmsEntry(entry: CollectionEntry<'docs'>): entry is CmsEntry {
 	return entry.data.type === 'cms';
 }
@@ -107,6 +121,7 @@ export const isEnglishEntry = createIsLangEntry('en');
 const docs = defineCollection({
 	schema: z.union([
 		baseSchema,
+		backendSchema,
 		cmsSchema,
 		integrationSchema,
 		migrationSchema,

src/content/docs/en/guides/backend.mdx

@@ -0,0 +1,27 @@
+---
+title: Use a backend service with Astro
+description: How to use a backend service to add authentication, storage and data
+i18nReady: true
+---
+import BackendGuidesNav from '~/components/BackendGuidesNav.astro';
+
+**Ready to add features like authentication, storage or data to your Astro project?** Follow one of our guides to integrate a backend service.
+
+## Backend service guides
+
+<BackendGuidesNav />
+
+Note that many of these pages are **stubs**: they're collections of resources waiting for your contribution!
+
+## What is a backend service?
+
+A backend service is a cloud-based system that helps you build and manage your backend infrastructure. It provides a set of tools and services for managing databases, user authentication, and other server-side functionality. This enables you to focus on building your applications without having to worry about managing the underlying infrastructure.
+
+## Why would I use a backend service?
+
+You might want to consider a backend service if your project has complex server-side needs, for example:
+- user signups and authentication
+- persistant data storage
+- user-uploaded asset storage
+- API generation
+- realtime communication

src/content/docs/en/guides/backend/appwriteio.mdx

@@ -0,0 +1,12 @@
+---
+title: Appwrite & Astro
+description: Add a backend to your project with Appwrite
+type: backend
+service: Appwrite
+stub: true
+---
+
+[Appwrite](https://appwrite.io/) is a self-hosted backend-as-a-service platform that provides authentication and account management, user preferences, database and storage persistence, cloud functions, localization, image manipulation, and other server-side utilities.
+
+## Official Resources
+- [AppWrite Demos for Astro](https://github.com/appwrite/demos-for-astro)

src/content/docs/en/guides/backend/google-firebase.mdx

@@ -0,0 +1,12 @@
+---
+title: Firebase & Astro
+description: Add a backend to your project with Supabase
+type: backend
+service: Firebase
+stub: true
+---
+import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
+import FileTree from '~/components/FileTree.astro'
+
+
+[Firebase](https://firebase.google.com/) is an app development platform that provides a NoSQL database, authentication, realtime subscriptions, functions, and storage.

src/content/docs/en/guides/backend/supabase.mdx

@@ -0,0 +1,12 @@
+---
+title: Supabase & Astro
+description: Add a backend to your project with Supabase
+type: backend
+service: Supabase
+stub: true
+---
+
+[Supabase](https://supabase.com/) is an open source Firebase alternative. It provides a Postgres database, authentication, edge functions, realtime subscriptions, and storage.
+
+## Community Resources
+- [Getting into the holiday spirit with Astro, React, and Supabase](https://www.aleksandra.codes/astro-supabase)

src/content/docs/en/guides/backend/tigris.mdx

@@ -0,0 +1,13 @@
+---
+title: Tigris & Astro
+description: Add a backend to your project with Tigris
+type: backend
+service: Tigris
+stub: true
+---
+
+Tigris is an open source alternative to MongoDB and DynamoDB. It is a serverless NoSQL database and search platform with their own official [Astro integration](https://github.com/tigrisdata/tigris-astro).
+
+## Official Resources
+- [Creating database-driven Astro sites with the Tigris Astro integration](https://www.tigrisdata.com/blog/astro-tigris-integration/)
+- [Tigris Astro Integration](https://www.tigrisdata.com/docs/sdkstools/astro/)

src/data/logos.ts

@@ -64,6 +64,9 @@ export const logos = LogoCheck({
 	docusaurus: { file: 'docusaurus.svg', padding: '.225em' },
 	nuxtjs: { file: 'nuxtjs.svg', padding: '.25em' },
 	keystonejs: { file: 'keystonejs.svg', padding: '.25em' },
+	appwriteio: { file: 'appwriteio.svg', padding: '.125em' },
+	supabase: { file: 'supabase.svg', padding: '.125em' },
+	tigris: { file: 'tigris.png', padding: '.3em .1em' },
 	cloudcannon: { file: 'cloudcannon.svg', padding: '.25em' },
 	markdoc: { file: 'markdoc.svg', padding: '.35em 0 .35em .1em' },
 	gitbook: { file: 'gitbook.svg', padding: '.25em' },

src/i18n/en/nav.ts

@@ -41,9 +41,10 @@ export default [
 	{ text: 'Recipes', header: true, type: 'learn', key: 'examples' },
 	{ text: 'Migrate to Astro', slug: 'guides/migrate-to-astro', key: 'guides/migrate-to-astro' },
 	{ text: 'Connect a CMS', slug: 'guides/cms', key: 'guides/cms' },
+	{ text: 'Add backend services', slug: 'guides/backend', key: 'guides/backend' },
 	{ text: 'Add integrations', slug: 'guides/integrations-guide', key: 'guides/integrations-guide' },
 	{ text: 'Deploy your site', slug: 'guides/deploy', key: 'guides/deploy' },
-	{ text: 'More Recipes', slug: 'recipes', key: 'guides/recipes' },
+	{ text: 'More recipes', slug: 'recipes', key: 'guides/recipes' },
 
 	{ text: 'Guides', header: true, type: 'learn', key: 'features' },
 	{
@@ -127,4 +128,4 @@ export default [
 		key: 'reference/error-reference',
 	},
 	{ text: 'NPM Package Format', slug: 'reference/publish-to-npm', key: 'guides/publish-to-npm' },
-] as const;
+] as const;

src/i18n/en/ui.ts

@@ -109,4 +109,6 @@ export default {
 	'feedback.success': 'Thanks! We received your feedback.',
 	// `<FileTree>` component
 	'fileTree.directoryLabel': 'Directory',
+	// Backend Guides vocabulary
+	'backend.navTitle': 'More backend service guides',
 };

src/i18n/ko/ui.ts

@@ -92,4 +92,6 @@ export default UIDictionary({
 	'feedback.button': '의견을 보내주세요',
 	// `<FileTree>` component
 	'fileTree.directoryLabel': '디렉토리',
+	// BaaS Guides vocabulary
+
 });

src/i18n/ru/ui.ts

@@ -79,4 +79,5 @@ export default UIDictionary({
 	'tutorial.getReady': 'Приготовьтесь к...',
 	'tutorial.trackerLabel': 'Трекер обучения',
 	'tutorial.unit': 'Единица',
+
 });

src/i18n/zh-cn/ui.ts

@@ -105,4 +105,6 @@ export default UIDictionary({
 	'feedback.success': '感谢！我们收到了你的反馈。',
 	// `<FileTree>` component
 	'fileTree.directoryLabel': '目录',
+	// BaaS Guides vocabulary
+
 });

src/layouts/BackendLayout.astro

@@ -0,0 +1,42 @@
+---
+import type { MarkdownHeading } from 'astro';
+import Aside from '~/components/Aside.astro';
+import BackendGuidesNav from '~/components/BackendGuidesNav.astro';
+import UIString from '~/components/UIString.astro';
+import type { BackendEntry } from '~/content/config';
+import { getGithubEditUrl } from '~/util/getGithubEditUrl';
+import MainLayout from './MainLayout.astro';
+
+export interface Props {
+	content: BackendEntry['data'];
+	headings: MarkdownHeading[];
+}
+
+const githubEditUrl = getGithubEditUrl(Astro);
+const {
+	content: { stub },
+} = Astro.props;
+---
+
+<MainLayout {...Astro.props}>
+	<slot />
+	{
+		stub && (
+			<Aside title="Expand this stub!">
+				This guide is a stub. <br />
+				Know more about how to use this backend service with Astro?{' '}
+				<a href={githubEditUrl} target="_blank">
+					<UIString key="rightSidebar.editPage" />
+				</a>
+			</Aside>
+		)
+	}
+	<h2><UIString key="backend.navTitle" /></h2>
+	<BackendGuidesNav minimal />
+</MainLayout>
+
+<style>
+	a {
+		font-weight: bold;
+	}
+</style>

src/layouts/LayoutSwitcher.astro

@@ -1,6 +1,7 @@
 ---
 import type { MarkdownHeading } from 'astro';
 import type { CollectionEntry } from 'astro:content';
+import BackendLayout from '~/layouts/BackendLayout.astro';
 import CMSLayout from '~/layouts/CMSLayout.astro';
 import DeployGuideLayout from '~/layouts/DeployGuideLayout.astro';
 import IntegrationLayout from '~/layouts/IntegrationLayout.astro';
@@ -18,7 +19,11 @@ const { data, headings } = Astro.props;
 ---
 
 {
-	data.type === 'cms' ? (
+	data.type === 'backend' ? (
+		<BackendLayout content={data} headings={headings}>
+			<slot />
+		</BackendLayout>
+	) : data.type === 'cms' ? (
 		<CMSLayout content={data} headings={headings}>
 			<slot />
 		</CMSLayout>