Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
import {
PlatformContentPayload,
RUNTIMES,
} from 'sentry-docs/components/frameworkSelector/frameworks';
import {resolvePlatformContent} from 'sentry-docs/components/platformContent';
import {getFileBySlugWithCache} from 'sentry-docs/mdx';

/**
* Serves the compiled MDX of a `<PlatformContent>` include as it applies to a framework running
* on a runtime, so a runtime's page can swap in framework snippets client-side
* (see `<FrameworkSelector>`).
*
* Only the combinations from `generateStaticParams` are built; there is no runtime rendering.
*/

export const dynamic = 'force-static';
export const dynamicParams = false;

export function generateStaticParams() {
return Object.entries(RUNTIMES).flatMap(([runtime, {frameworks, includePaths}]) =>
frameworks.flatMap(({key: framework}) =>
includePaths.map(includePath => ({
platform: 'javascript',
runtime,
framework,
includePath: includePath.split('/'),
}))
)
);
}

type SlugFile = Awaited<ReturnType<typeof getFileBySlugWithCache>>;

async function tryGetFile(slug: string): Promise<SlugFile | undefined> {
try {
return await getFileBySlugWithCache(slug);
} catch {
return undefined;
}
}

/**
* Resolves an include for a framework on a runtime:
* 1. `<platform>.<runtime>.<framework>`, for snippets specific to both
* 2. On Node.js, the framework guide's content, which falls back to Node.js
* Elsewhere, only a `<platform>.<framework>` snippet, to not pull in Node.js content
* 3. The runtime guide's own content
*/
async function resolveForFramework(
includePath: string,
platform: string,
runtime: string,
framework: string
): Promise<SlugFile | null | undefined> {
const base = `platform-includes/${includePath}/${platform}`;

const doc = await tryGetFile(`${base}.${runtime}.${framework}`);
if (doc) {
return doc;
}

if (runtime === 'node') {
return resolvePlatformContent({
includePath,
path: ['platforms', platform, 'guides', framework],
});
}

return (
(await tryGetFile(`${base}.${framework}`)) ??
resolvePlatformContent({
includePath,
path: ['platforms', platform, 'guides', runtime],
})
);
}

const INCLUDE_RE = /<Include\s+name=["']([^"']+)["']/g;
const PLATFORM_CONTENT_RE = /<PlatformContent\s+includePath=["']([^"']+)["']/g;

async function collectNested(
source: string,
resolve: (includePath: string) => Promise<SlugFile | null | undefined>,
payload: PlatformContentPayload
) {
for (const [, rawName] of source.matchAll(INCLUDE_RE)) {
const name = rawName.replace(/\.mdx$/, '');
if (name in payload.includes) {
continue;
}
// Missing includes render nothing, same as <Include>.
const doc = await tryGetFile(`includes/${name}`);
if (doc) {
payload.includes[name] = doc.mdxSource;
await collectNested(doc.matter.content, resolve, payload);
}
}

for (const [, includePath] of source.matchAll(PLATFORM_CONTENT_RE)) {
if (includePath in payload.platformContents) {
continue;
}
const doc = await resolve(includePath);
payload.platformContents[includePath] = doc?.mdxSource ?? null;
if (doc) {
await collectNested(doc.matter.content, resolve, payload);
}
}
}

async function buildPayload(
includePath: string,
resolve: (includePath: string) => Promise<SlugFile | null | undefined>
): Promise<PlatformContentPayload> {
const doc = await resolve(includePath);
const payload: PlatformContentPayload = {
changed: false,
code: doc?.mdxSource ?? null,
includes: {},
platformContents: {},
};
if (doc) {
await collectNested(doc.matter.content, resolve, payload);
}
return payload;
}

export async function GET(
_request: Request,
{
params,
}: {
params: Promise<{
framework: string;
includePath: string[];
platform: string;
runtime: string;
}>;
}
) {
const {platform, runtime, framework, includePath} = await params;
const resolve = (path: string) =>
resolveForFramework(path, platform, runtime, framework);

const resolveForRuntime = (path: string) =>
resolvePlatformContent({
includePath: path,
path: ['platforms', platform, 'guides', runtime],
});

const [payload, runtimePayload] = await Promise.all([
buildPayload(includePath.join('/'), resolve),
buildPayload(includePath.join('/'), resolveForRuntime),
]);
payload.changed =
payload.code !== runtimePayload.code ||
JSON.stringify(payload.platformContents) !==
JSON.stringify(runtimePayload.platformContents);

return Response.json(payload);
}
10 changes: 6 additions & 4 deletions app/platform-redirect/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import {SmartLink} from 'sentry-docs/components/smartLink';
import {extractPlatforms, getDocsRootNode, nodeForPath} from 'sentry-docs/docTree';
import {setServerContext} from 'sentry-docs/serverContext';

import {platformUrlFor, sanitizeNext} from './utils';
import {landingPageFallbackGuide, platformUrlFor, sanitizeNext} from './utils';

export const metadata: Metadata = {
robots: 'noindex',
Expand Down Expand Up @@ -142,9 +142,11 @@ export default async function Page(props: {

const requestedPlatform = Array.isArray(platform) ? platform[0] : platform;
if (requestedPlatform) {
const validPlatform = platformOrGuideList.find(
p => p.key === requestedPlatform?.toLowerCase()
);
const requestedKey = requestedPlatform.toLowerCase();
const fallbackKey = landingPageFallbackGuide(rootNode, requestedKey);
const validPlatform =
platformOrGuideList.find(p => p.key === requestedKey) ??
platformOrGuideList.find(p => p.key === fallbackKey);
if (validPlatform) {
return redirect(platformUrlFor(validPlatform.url, sanitized));
}
Expand Down
45 changes: 44 additions & 1 deletion app/platform-redirect/utils.spec.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,54 @@
import type {DocNode} from 'sentry-docs/docTree';
import {describe, expect, it} from 'vitest';

import {platformUrlFor, sanitizeNext} from './utils';
import {landingPageFallbackGuide, platformUrlFor, sanitizeNext} from './utils';

const path = (next: string) => sanitizeNext(next).pathname;
const hash = (next: string) => sanitizeNext(next).hash;
const REJECTED = {pathname: '', hash: ''};

describe('landingPageFallbackGuide', () => {
const node = (
slug: string,
frontmatter: Record<string, unknown> = {},
children: DocNode[] = []
) => ({slug, frontmatter, children, missing: false, path: slug}) as unknown as DocNode;

const rootNode = node('', {}, [
node('platforms', {}, [
node('javascript', {}, [
node('guides', {}, [
node('express', {
inheritCommonContent: false,
fallbackGuide: 'javascript.node',
}),
node('nestjs', {fallbackGuide: 'javascript.node'}),
node('cordova', {inheritCommonContent: false}),
]),
]),
]),
]);

it('returns the fallback guide of a landing page guide', () => {
expect(landingPageFallbackGuide(rootNode, 'javascript.express')).toBe(
'javascript.node'
);
});

it('returns nothing for a guide that inherits the common content', () => {
expect(landingPageFallbackGuide(rootNode, 'javascript.nestjs')).toBeUndefined();
});

it('returns nothing for a landing page guide without a fallback guide', () => {
expect(landingPageFallbackGuide(rootNode, 'javascript.cordova')).toBeUndefined();
});

it('returns nothing for a platform or an unknown guide', () => {
expect(landingPageFallbackGuide(rootNode, 'javascript')).toBeUndefined();
expect(landingPageFallbackGuide(rootNode, 'javascript.unknown')).toBeUndefined();
});
});

describe('sanitizeNext', () => {
it('should return an empty string for external URLs', () => {
expect(sanitizeNext('http://example.com')).toEqual(REJECTED);
Expand Down
22 changes: 22 additions & 0 deletions app/platform-redirect/utils.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,25 @@
import {DocNode, nodeForPath} from 'sentry-docs/docTree';

/**
* Returns the `fallbackGuide` key (e.g. `javascript.node`) of a guide that is a single
* landing page (`inheritCommonContent: false`), such as `javascript.express`. The pages
* that such a guide does not have are in its fallback guide.
*/
export function landingPageFallbackGuide(
rootNode: DocNode,
key: string
): string | undefined {
const [platform, guide] = key.split('.');
if (!guide) {
return undefined;
}
const guideNode = nodeForPath(rootNode, ['platforms', platform, 'guides', guide]);
if (guideNode?.frontmatter.inheritCommonContent !== false) {
return undefined;
}
return guideNode.frontmatter.fallbackGuide;
}

// Parse base only — never part of the return value, and only compared against itself
const PARSE_BASE = 'https://sanitize.invalid';

Expand Down
23 changes: 23 additions & 0 deletions docs/contributing/pages/components.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,7 @@ Attributes:

- `includePath` (string) - the subfolder within `/includes` to map to
- `platform` (string) - defaults to the `platform` value from the page context
- `switchable` (boolean) - lets a surrounding [`FrameworkSelector`](#frameworkselector) swap the include for the selected framework's version

Some notes:

Expand All @@ -371,6 +372,28 @@ Some notes:

Note: This currently causes issues with tableOfContents generation, so its recommended to disable the TOC when using it.

## FrameworkSelector

Adds a framework dropdown to a runtime's quick start, such as the Node.js, Bun, and Deno guides. Selecting a framework that doesn't have its own SDK (Express, Fastify, Koa, Hapi) swaps every `<PlatformContent switchable />` inside the selector for that framework's version. Selecting a framework that has its own guide (Next.js, Nuxt, and others) opens that guide. The selection is kept in the `?framework=` query parameter.

```markdown {tabTitle:Example}
<FrameworkSelector runtime="node">

<PlatformContent includePath="getting-started-install" switchable />

</FrameworkSelector>
```

The runtimes, their frameworks, and their switchable include paths are configured in `src/components/frameworkSelector/frameworks.ts`.

The framework snippets are only shown after a reader selects the framework, so they're easy to miss when you change content:

- `platform-includes/<includePath>/javascript.<framework>.mdx` (for example, `javascript.express.mdx`) shows up on the Node.js, Bun, **and** Deno quick starts. Put snippets that only apply to one runtime in `javascript.<runtime>.<framework>.mdx`, for example `javascript.node.express.mdx`.
- On Node.js, a framework without its own file uses the Node.js content. On Bun and Deno, it uses the runtime's own content.
- Every `switchable` include path has to be listed in the runtime's `includePaths` in `frameworks.ts`. If it isn't, the framework version isn't built and the page quietly keeps showing the runtime's content. `frameworks.spec.ts` fails when the two get out of sync.
- The framework snippets aren't part of the runtime page's [Markdown export](/contributing/pages/llm-support/). Keep framework-specific guidance that agents need, such as error handling options, on the framework's own guide page too, for example `docs/platforms/javascript/guides/express/index.mdx`.
- To review a change, open the quick start with the framework selected, for example `/platforms/javascript/guides/node/?framework=express`, for each runtime the file applies to.

## PlatformIdentifier

Render terms in the correct case within the body text of a page (not in code samples) based on the platform case_style setting:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,47 @@ Sentry.init({
});
```

## Options

### `shouldHandleError`

A function that decides whether an error is captured. By default, errors with a 5xx status code (and errors with a 2xx status code or lower) are captured, and errors with a 3xx or 4xx status code aren't.

```typescript
declare function shouldHandleError(
error: Error,
request: FastifyRequest,
reply: FastifyReply
): boolean;
```

```javascript
Sentry.init({
dsn: "___PUBLIC_DSN___",
integrations: [
Sentry.fastifyIntegration({
shouldHandleError(error, request, reply) {
return reply.statusCode >= 500;
},
}),
],
});
```

If you use TypeScript, cast the request and reply to get full type safety:

```typescript
import type { FastifyRequest, FastifyReply } from "fastify";

Sentry.fastifyIntegration({
shouldHandleError(error, minimalRequest, minimalReply) {
const request = minimalRequest as FastifyRequest;
const reply = minimalReply as FastifyReply;
return reply.statusCode >= 500;
},
});
```

## Supported Versions

- `fastify`: `^3.21.0 || ^4.0.0`
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Scrubbing Sensitive Data"
description: "Learn about filtering or scrubbing sensitive data within the Sentry JavaScript SDK, so that data is not sent with the event. You can also configure server-side scrubbing to ensure the data is not stored."
customCanonicalTag: "/platforms/javascript/guides/koa/data-management/sensitive-data/"
customCanonicalTag: "/platforms/javascript/guides/node/data-management/sensitive-data/"
sidebar_order: 100
keywords:
- pii
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Rollup
description: "Upload your source maps with the Sentry Rollup Plugin."
sidebar_order: 5
customCanonicalTag: "/platforms/javascript/guides/koa/sourcemaps/uploading/rollup/"
customCanonicalTag: "/platforms/javascript/guides/node/sourcemaps/uploading/rollup/"
---

<Alert>
Expand Down
Loading
Loading