fix: resolve prerender error with ExternalCodeSnippet

content/docs/ai/ai-rules-neon-auth.md

@@ -0,0 +1,74 @@
+---
+title: 'AI Rules: Neon Auth'
+subtitle: 'Context rules for AI tools to help implement authentication with Stack Auth and Neon databases'
+enableTableOfContents: true
+---
+
+## How to use
+
+If you use Cursor or any AI-based code assistant that supports custom rules:
+
+1. Create a `.cursor/rules` directory in your project
+2. Copy the rules below into `.cursor/rules/neon-auth.mdc`
+3. (Optional) Re-index your project in Cursor to pick up the new rules
+
+For other AI tools, use their respective "include file" features:
+- GitHub Copilot: Add `#<filename>` in your comments
+- Zed: Use the `/file` command
+
+## Rules
+
+```
+# Neon Auth Rules
+
+This file contains context rules for AI tools to help implement authentication with Stack Auth and Neon databases.
+
+## Overview
+
+These rules provide guidance for AI tools when implementing authentication flows using Stack Auth with Neon databases.
+
+## Implementation Guidelines
+
+1. Use the Stack Auth library for authentication
+2. Connect to Neon database using the provided connection string
+3. Store user credentials securely
+4. Implement proper error handling for authentication failures
+
+## Example Code
+
+```typescript
+import { StackAuth } from 'stack-auth';
+import { neon } from '@neondatabase/serverless';
+
+// Initialize Stack Auth
+const auth = new StackAuth({
+  clientId: process.env.AUTH_CLIENT_ID,
+  clientSecret: process.env.AUTH_CLIENT_SECRET
+});
+
+// Connect to Neon database
+const sql = neon(process.env.DATABASE_URL);
+
+// Authenticate user
+async function authenticateUser(email, password) {
+  try {
+    const user = await auth.login(email, password);
+
+    // Store user session in database
+    await sql`INSERT INTO sessions (user_id, token) VALUES (${user.id}, ${user.token})`;
+
+    return user;
+  } catch (error) {
+    console.error('Authentication failed:', error);
+    throw new Error('Authentication failed');
+  }
+}
+```
+
+## Security Considerations
+
+- Never store plaintext passwords
+- Use environment variables for sensitive credentials
+- Implement rate limiting for authentication attempts
+- Use HTTPS for all connections
+```

content/docs/shared-content/code-snippet.md

@@ -0,0 +1,11 @@
+---
+updatedOn: '2024-03-21T19:51:53Z'
+---
+
+<CodeSnippet 
+  url="{url}"
+  language="{language}"
+  title="{title}"
+  fallback="{fallback}"
+  showSource="{showSource}"
+/>

content/docs/shared-content/index.js

@@ -12,6 +12,7 @@ const sharedMdxComponents = {
   FeatureBetaProps: 'shared-content/feature-beta-props',
   MigrationAssistant: 'shared-content/migration-assistant',
   LinkAPIKey: 'shared-content/manage-api-keys',
+  // ExternalCodeSnippet removed to fix prerender error
 };
 
 module.exports = sharedMdxComponents;

content/docs/sidebar.yaml

@@ -741,6 +741,8 @@
           slug: ai/ai-concepts
         - title: The pgvector extension
           slug: extensions/pgvector
+        - title: AI Rules for Neon Auth
+          slug: ai/ai-rules-neon-auth
         - title: AI integrations
           slug: ai/langchain
           items:

docs/code-snippet-usage.md

@@ -0,0 +1,91 @@
+# CodeSnippet Component Documentation
+
+The `CodeSnippet` component allows technical writers to embed raw code content from external sources directly into the documentation pages. This component fetches files at build time and displays them as code blocks with syntax highlighting.
+
+## Usage
+
+```jsx
+import CodeSnippet from 'components/shared/code-snippet';
+
+<CodeSnippet 
+  url="https://raw.githubusercontent.com/neondatabase/neon/main/README.md"
+  title="Neon README"
+/>
+```
+
+## Props
+
+| Prop        | Type      | Default                         | Description                                             |
+|-------------|-----------|--------------------------------|---------------------------------------------------------|
+| url         | string    | (required)                     | URL to the raw file                                     |
+| language    | string    | ''                             | Language for syntax highlighting (defaults to file extension) |
+| className   | string    | ''                             | Additional CSS classes to apply to the component         |
+| fallback    | string    | 'Failed to load code snippet'  | Content to display if loading fails                     |
+| showSource  | boolean   | true                           | Whether to show a link to the source                    |
+| title       | string    | ''                             | Optional title to display above the snippet             |
+
+## Features
+
+- **Build-time Fetching**: Files are fetched once at build time for optimal performance and SEO, with no automatic revalidation.
+- **Syntax Highlighting**: Automatically detects language from file extension or uses provided language prop.
+- **Error Handling**: Displays fallback content if the file cannot be fetched.
+- **Source Link**: Optionally shows a link to the original source file.
+- **Multi-file Support**: Works with various file types (.md, .ts, .js, .py, etc.).
+
+## Examples
+
+### TypeScript File
+
+```jsx
+<CodeSnippet 
+  url="https://raw.githubusercontent.com/neondatabase/serverless/main/index.ts"
+  title="Neon Serverless Driver"
+/>
+```
+
+### Markdown File as Raw Text
+
+```jsx
+<CodeSnippet 
+  url="https://raw.githubusercontent.com/neondatabase/neon/main/README.md"
+  title="Neon README"
+/>
+```
+
+### Custom Language Specification
+
+```jsx
+<CodeSnippet 
+  url="https://raw.githubusercontent.com/neondatabase/neon/main/config.txt"
+  language="yaml"
+  title="Configuration File"
+/>
+```
+
+## Usage in Markdown Files
+
+Once the CodeSnippet component is registered in the docs pipeline, you can use it directly in Markdown files:
+
+```md
+<CodeSnippet 
+  url="https://raw.githubusercontent.com/neondatabase/serverless/main/index.ts"
+  title="Neon Serverless Driver"
+/>
+```
+
+### Available Props in Markdown
+
+| Prop        | Type      | Default                         | Description                                             |
+|-------------|-----------|--------------------------------|---------------------------------------------------------|
+| url         | string    | (required)                     | URL to the raw file                                     |
+| language    | string    | ''                             | Language for syntax highlighting (defaults to file extension) |
+| title       | string    | ''                             | Optional title to display above the snippet             |
+| fallback    | string    | 'Failed to load code snippet'  | Content to display if loading fails                     |
+| showSource  | string    | 'true'                         | Whether to show a link to the source (use 'true' or 'false' as string) |
+
+## Best Practices
+
+1. Always use raw URLs from the GitHub repository (e.g., `https://raw.githubusercontent.com/...`).
+2. Include a descriptive title to help readers understand the content's context.
+3. For critical content, implement a fallback message in case the remote content fails to load.
+4. Use the `language` prop when the file extension doesn't match the actual content type.

docs/external-code-snippet-usage.md

@@ -0,0 +1,91 @@
+# ExternalCodeSnippet Component Documentation
+
+The `ExternalCodeSnippet` component allows technical writers to embed raw code content from external sources directly into the documentation pages. This component fetches files at build time and displays them as code blocks with syntax highlighting.
+
+## Usage
+
+```jsx
+import ExternalCodeSnippet from 'components/shared/external-code-snippet';
+
+<ExternalCodeSnippet 
+  url="https://raw.githubusercontent.com/neondatabase/neon/main/README.md"
+  title="Neon README"
+/>
+```
+
+## Props
+
+| Prop        | Type      | Default                         | Description                                             |
+|-------------|-----------|--------------------------------|---------------------------------------------------------|
+| url         | string    | (required)                     | URL to the raw file                                     |
+| language    | string    | ''                             | Language for syntax highlighting (defaults to file extension) |
+| className   | string    | ''                             | Additional CSS classes to apply to the component         |
+| fallback    | string    | 'Failed to load code snippet'  | Content to display if loading fails                     |
+| showSource  | boolean   | true                           | Whether to show a link to the source                    |
+| title       | string    | ''                             | Optional title to display above the snippet             |
+
+## Features
+
+- **Build-time Fetching**: Files are fetched once at build time for optimal performance and SEO, with no automatic revalidation.
+- **Syntax Highlighting**: Automatically detects language from file extension or uses provided language prop.
+- **Error Handling**: Displays fallback content if the file cannot be fetched.
+- **Source Link**: Optionally shows a link to the original source file.
+- **Multi-file Support**: Works with various file types (.md, .ts, .js, .py, etc.).
+
+## Examples
+
+### TypeScript File
+
+```jsx
+<ExternalCodeSnippet 
+  url="https://raw.githubusercontent.com/neondatabase/serverless/main/index.ts"
+  title="Neon Serverless Driver"
+/>
+```
+
+### Markdown File as Raw Text
+
+```jsx
+<ExternalCodeSnippet 
+  url="https://raw.githubusercontent.com/neondatabase/neon/main/README.md"
+  title="Neon README"
+/>
+```
+
+### Custom Language Specification
+
+```jsx
+<ExternalCodeSnippet 
+  url="https://raw.githubusercontent.com/neondatabase/neon/main/config.txt"
+  language="yaml"
+  title="Configuration File"
+/>
+```
+
+## Usage in Markdown Files
+
+Once the ExternalCodeSnippet component is registered in the docs pipeline, you can use it directly in Markdown files:
+
+```md
+<ExternalCodeSnippet 
+  url="https://raw.githubusercontent.com/neondatabase/serverless/main/index.ts"
+  title="Neon Serverless Driver"
+/>
+```
+
+### Available Props in Markdown
+
+| Prop        | Type      | Default                         | Description                                             |
+|-------------|-----------|--------------------------------|---------------------------------------------------------|
+| url         | string    | (required)                     | URL to the raw file                                     |
+| language    | string    | ''                             | Language for syntax highlighting (defaults to file extension) |
+| title       | string    | ''                             | Optional title to display above the snippet             |
+| fallback    | string    | 'Failed to load code snippet'  | Content to display if loading fails                     |
+| showSource  | string    | 'true'                         | Whether to show a link to the source (use 'true' or 'false' as string) |
+
+## Best Practices
+
+1. Always use raw URLs from the GitHub repository (e.g., `https://raw.githubusercontent.com/...`).
+2. Include a descriptive title to help readers understand the content's context.
+3. For critical content, implement a fallback message in case the remote content fails to load.
+4. Use the `language` prop when the file extension doesn't match the actual content type.

src/app/examples/code-snippet/page.jsx

@@ -0,0 +1,44 @@
+import CodeSnippet from 'components/shared/code-snippet';
+import getMetadata from 'utils/get-metadata';
+
+export const metadata = getMetadata({
+  title: 'Code Snippet Example',
+  description: 'Example of using the CodeSnippet component',
+});
+
+const CodeSnippetExamplePage = () => (
+  <div className="container mx-auto px-4 py-8">
+    <h1 className="mb-6 text-3xl font-bold">Code Snippet Examples</h1>
+
+    <h2 className="mb-4 mt-8 text-2xl font-semibold">Markdown File Example</h2>
+    <p className="mb-4">This example loads a Markdown file as raw text:</p>
+    <CodeSnippet
+      url="https://raw.githubusercontent.com/neondatabase/neon/main/README.md"
+      title="Neon README"
+    />
+
+    <h2 className="mb-4 mt-8 text-2xl font-semibold">TypeScript File Example</h2>
+    <p className="mb-4">This example loads a TypeScript file:</p>
+    <CodeSnippet
+      url="https://raw.githubusercontent.com/neondatabase/serverless/main/index.ts"
+      title="Neon Serverless Driver"
+    />
+
+    <h2 className="mb-4 mt-8 text-2xl font-semibold">Error Handling Example</h2>
+    <p className="mb-4">This example shows how errors are handled:</p>
+    <CodeSnippet
+      url="https://raw.githubusercontent.com/neondatabase/non-existent-repo/main/file.txt"
+      fallback="This repository or file doesn't exist"
+      title="Non-existent Repository"
+    />
+
+    <h2 className="mb-4 mt-8 text-2xl font-semibold">Component in Markdown Example</h2>
+    <p className="mb-4">This example shows how to use CodeSnippet directly in Markdown files:</p>
+    <div className="mb-8 rounded bg-gray-new-98 p-4 dark:bg-gray-new-10">
+      &lt;CodeSnippet url="https://raw.githubusercontent.com/neondatabase/serverless/main/index.ts"
+      title="Neon Serverless Driver" /&gt;
+    </div>
+  </div>
+);
+
+export default CodeSnippetExamplePage;

src/components/pages/doc/include-block/include-block.jsx

@@ -6,15 +6,26 @@ import { DOCS_DIR_PATH } from 'constants/content';
 import { getPostBySlug } from 'utils/api-docs';
 
 const IncludeBlock = ({ url, ...props }) => {
-  const post = getPostBySlug(url, DOCS_DIR_PATH);
+  // For local files, continue with existing logic
+  try {
+    const post = getPostBySlug(url, DOCS_DIR_PATH);
 
-  // Replace placeholders with actual prop values
-  let contentWithProps = post.content;
-  Object.entries(props).forEach(([key, value]) => {
-    contentWithProps = contentWithProps.replace(new RegExp(`{${key}}`, 'g'), value);
-  });
+    // Safety check to avoid null reference errors
+    if (!post) {
+      return <div className="text-red-500 p-4">Failed to load content: {url}</div>;
+    }
 
-  return <Content content={contentWithProps} />;
+    // Replace placeholders with actual prop values
+    let contentWithProps = post.content;
+    Object.entries(props).forEach(([key, value]) => {
+      contentWithProps = contentWithProps.replace(new RegExp(`{${key}}`, 'g'), value);
+    });
+
+    return <Content content={contentWithProps} />;
+  } catch (error) {
+    console.error(`Error loading content for ${url}:`, error);
+    return <div className="text-red-500 p-4">Error loading content: {url}</div>;
+  }
 };
 
 IncludeBlock.propTypes = {