From d9ae286c4a2c5b51cea23373ca8a31d1b1d00b80 Mon Sep 17 00:00:00 2001 From: Kian Newman-Hazel Date: Tue, 25 Feb 2025 15:18:23 +0000 Subject: [PATCH 1/2] [Docs Site] Support EC props in GitHubCode and TypeScriptExample --- src/components/GitHubCode.astro | 12 +++- src/components/TypeScriptExample.astro | 48 ++++--------- .../docs/style-guide/components/code.mdx | 52 -------------- .../style-guide/components/github-code.mdx | 27 ++++++- .../components/typescript-example.mdx | 71 +++++++++++++++++++ .../docs/workers/get-started/prompting.mdx | 4 +- 6 files changed, 121 insertions(+), 93 deletions(-) create mode 100644 src/content/docs/style-guide/components/typescript-example.mdx diff --git a/src/components/GitHubCode.astro b/src/components/GitHubCode.astro index f7442339733d155..563afac572ee0a4 100644 --- a/src/components/GitHubCode.astro +++ b/src/components/GitHubCode.astro @@ -1,6 +1,8 @@ --- import { z } from "astro:schema"; import { Code } from "@astrojs/starlight/components"; +import TypeScriptExample from "./TypeScriptExample.astro"; +import type { ComponentProps } from "astro/types"; type Props = z.infer; @@ -15,7 +17,9 @@ const props = z .transform((val) => val.split("-").map(Number)) .optional(), tag: z.string().optional(), + code: z.custom>().optional(), }) + .strict() .refine( (val) => { return !(val.lines && val.tag); @@ -23,7 +27,7 @@ const props = z { message: "Lines and tag are mutually exclusive filters." }, ); -const { repo, commit, file, lang, lines, tag } = props.parse(Astro.props); +const { repo, commit, file, lang, lines, tag, code } = props.parse(Astro.props); const res = await fetch( `https://gh-code.developers.cloudflare.com/${repo}/${commit}/${file}`, @@ -64,6 +68,10 @@ if (lines) { contentLines = contentLines.filter( (line) => !/<[/]?docs-tag name=".*">/.test(line), ); + +const Wrapper = lang === "ts" ? TypeScriptExample : Fragment; --- - + + + diff --git a/src/components/TypeScriptExample.astro b/src/components/TypeScriptExample.astro index f8e1753769f1863..43b05c50479e960 100644 --- a/src/components/TypeScriptExample.astro +++ b/src/components/TypeScriptExample.astro @@ -4,39 +4,20 @@ import tsBlankSpace from "ts-blank-space"; import { format } from "prettier"; import { parse } from "node-html-parser"; import { Code, Tabs, TabItem } from "@astrojs/starlight/components"; +import type { ComponentProps } from "astro/types"; -type Props = z.infer; +type Props = z.input; const props = z .object({ filename: z.string().optional(), - tabsWrapper: z.boolean().default(true), playground: z.boolean().default(false), + code: z.custom>().optional(), }) - .or( - z.object({ - filename: z.object({ - js: z.string(), - ts: z.string(), - }), - tabsWrapper: z.boolean().default(true), - playground: z.boolean().default(false), - }), - ); - -const { filename, tabsWrapper, playground } = props.parse(Astro.props); + .strict(); -let jsTitle, tsTitle; +const { filename, playground, code } = props.parse(Astro.props); -if (filename) { - if (typeof filename === "object") { - jsTitle = filename.js; - tsTitle = filename.ts; - } else { - jsTitle = filename.replace(".ts", ".js"); - tsTitle = filename; - } -} const slot = await Astro.slots.render("default"); const html = parse(slot); @@ -49,31 +30,30 @@ if (!copy) { ); } -let code = copy.attributes["data-code"]; +let raw = copy.attributes["data-code"]; -if (!code) { +if (!raw) { throw new Error( `[TypeScriptExample] Unable to find data-code attribute on copy button.`, ); } -code = code.replace(/\u007f/g, "\n"); - -const js = await format(tsBlankSpace(code), { parser: "babel", useTabs: true }); +raw = raw.replace(/\u007f/g, "\n"); -const TabsWrapper = tabsWrapper ? Tabs : Fragment; +const js = await format(tsBlankSpace(raw), { parser: "babel", useTabs: true }); --- - + - + - + diff --git a/src/content/docs/style-guide/components/code.mdx b/src/content/docs/style-guide/components/code.mdx index cf6398367b93c14..241f877a3e0a9a3 100644 --- a/src/content/docs/style-guide/components/code.mdx +++ b/src/content/docs/style-guide/components/code.mdx @@ -100,55 +100,3 @@ export default { }; ``` ```` - -## TypeScript examples - -The `TypeScriptExample` component uses [`ts-blank-space`](https://github.com/bloomberg/ts-blank-space) to remove TypeScript-specific syntax from your example and provide a JavaScript tab. This reduces maintenance burden by only having a single example to maintain. - -:::note -Some TypeScript syntax influences runtime behaviour, and cannot be stripped. - -Please refer to the [Unsupported Syntax](https://github.com/bloomberg/ts-blank-space?tab=readme-ov-file#unsupported-syntax) section of the project's README. -::: - -### Input - -* `filename` `string | { js: string, ts: string }` (optional) - * If a single TypeScript filename is passed, this will be used for JavaScript but with a `.js` file extension. - * `` - * To specify different filenames for the two languages, pass an object with a `js` and `ts` filename including extensions. - * `` -* `tabsWrapper` `boolean` (optional) - * When set to `false`, this component will not render `` components. - * This allows you to include the JS/TS tabs in your own `` and add ``s before/after, i.e for Python examples. -* `playground` `boolean` (optional) - * When set to `true`, a "Open Worker in Playground" link will render on the JavaScript codeblock. - -````mdx live -import { TypeScriptExample } from "~/components"; - - -```ts -interface Environment { - KV: KVNamespace; -} - -export default { - async fetch(req, env, ctx): Promise { - if (req !== "POST") { - return new Response("Method Not Allowed", { - status: 405, - headers: { - "Allow": "POST" - } - }); - } - - await env.KV.put("foo", "bar"); - - return new Response(); - } -} satisfies ExportedHandler -``` - -```` diff --git a/src/content/docs/style-guide/components/github-code.mdx b/src/content/docs/style-guide/components/github-code.mdx index 3e653c7c4650796..2a2c73eb952619c 100644 --- a/src/content/docs/style-guide/components/github-code.mdx +++ b/src/content/docs/style-guide/components/github-code.mdx @@ -2,6 +2,8 @@ title: GitHubCode --- +import { GitHubCode } from "~/components"; + The `GitHubCode` component allows you to include files from Cloudflare repositories. The remote content can be filtered by lines or a region enclosed in tags. @@ -14,14 +16,25 @@ import { GitHubCode } from "~/components"; ## Usage -```mdx live -import { GitHubCode } from "~/components"; + +```mdx ``` @@ -109,6 +122,8 @@ The long (40-characters) Git commit hash to pull from, for example `ab3951b5c953 The language to use for the code block, for example `rs`. +If the `lang` is `ts`, the [`TypeScriptExample`](/style-guide/components/typescript-example/) component will be used to provide a JavaScript tab as well. + ### `lines` **type:** `string` @@ -121,4 +136,10 @@ A range of lines to filter the content using, for example `1-3`. A region to filter the content with, for example `no-logging`. -This should be represented as starting `` and closing `` comments in the source file. \ No newline at end of file +This should be represented as starting `` and closing `` comments in the source file. + +### `code` + +**type**: `object` + +Props to pass to the [Expressive Code component](https://expressive-code.com/key-features/code-component/). \ No newline at end of file diff --git a/src/content/docs/style-guide/components/typescript-example.mdx b/src/content/docs/style-guide/components/typescript-example.mdx new file mode 100644 index 000000000000000..bf9c38b7d981cb7 --- /dev/null +++ b/src/content/docs/style-guide/components/typescript-example.mdx @@ -0,0 +1,71 @@ +--- +title: TypeScript example +--- + +## TypeScript examples + +The `TypeScriptExample` component uses [`ts-blank-space`](https://github.com/bloomberg/ts-blank-space) to remove TypeScript-specific syntax from your example and provide a JavaScript tab. This reduces maintenance burden by only having a single example to maintain. + +This component is automatically used in the [`GitHubCode`](/style-guide/components/github-code/) component when the `lang` is set to `ts`. + +:::note +Some TypeScript syntax influences runtime behaviour, and cannot be stripped. + +Please refer to the [Unsupported Syntax](https://github.com/bloomberg/ts-blank-space?tab=readme-ov-file#unsupported-syntax) section of the project's README. +::: + +## Component + +````mdx live +import { TypeScriptExample } from "~/components"; + + +```ts +interface Environment { + KV: KVNamespace; +} + +export default { + async fetch(req, env, ctx): Promise { + if (req !== "POST") { + return new Response("Method Not Allowed", { + status: 405, + headers: { + "Allow": "POST" + } + }); + } + + await env.KV.put("foo", "bar"); + + return new Response(); + } +} satisfies ExportedHandler +``` + +```` + + +## `` Props + +### `filename` + +**type:** `string` + +An optional filename, ending in `.ts`. + +`.ts` will be replaced by `.js` for the JavaScript tab. + +### `playground` + +**type:** `boolean` + +If set to `true`, a [`Run Worker in Playground`](/style-guide/components/code/#playground) button will appear on the JavaScript tab. + +### `code` + +**type**: `object` + +Props to pass to the [Expressive Code component](https://expressive-code.com/key-features/code-component/). + +These props will apply to both code blocks and so options like `collapse` may not work as expected, as lines may be removed from the TypeScript code. \ No newline at end of file diff --git a/src/content/docs/workers/get-started/prompting.mdx b/src/content/docs/workers/get-started/prompting.mdx index 29156f9ac7ed003..7b91d86aef411b3 100644 --- a/src/content/docs/workers/get-started/prompting.mdx +++ b/src/content/docs/workers/get-started/prompting.mdx @@ -1003,9 +1003,9 @@ Depending on the model and user prompt, it may generate invalid code, configurat ### Passing a system prompt -If you are building an AI application that will itself generate code, you can additionally use the prompt above as a "system prompt", which will give the LLM additional information on how to structure the output code. For example: +If you are building an AI application that will itself generate code, you can additionally use the prompt above as a "system prompt", which will give the LLM additional information on how to structure the output code. For example: - + ```ts import workersPrompt from "./workersPrompt.md" From eaf13fc0e1b3829dcef33b7fa9a91ad16bf492fb Mon Sep 17 00:00:00 2001 From: Kian Newman-Hazel Date: Tue, 25 Feb 2025 15:39:19 +0000 Subject: [PATCH 2/2] fix file usage --- src/content/docs/agents/examples/using-ai-models.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/docs/agents/examples/using-ai-models.mdx b/src/content/docs/agents/examples/using-ai-models.mdx index a1a2d4223142f83..5287b0fa5819150 100644 --- a/src/content/docs/agents/examples/using-ai-models.mdx +++ b/src/content/docs/agents/examples/using-ai-models.mdx @@ -26,7 +26,7 @@ Modern [reasoning models](https://platform.openai.com/docs/guides/reasoning) or Instead of buffering the entire response, or risking the client disconecting, you can stream the response back to the client by using the [WebSocket API](/agents/examples/websockets/). - + ```ts import { Agent } from "agents-sdk" @@ -85,7 +85,7 @@ You can use [any of the models available in Workers AI](/workers-ai/models/) wit Workers AI supports streaming responses out-of-the-box by setting `stream: true`, and we strongly recommend using them to avoid buffering and delaying responses, especially for larger models or reasoning models that require more time to generate a response. - + ```ts import { Agent } from "agents-sdk" @@ -135,7 +135,7 @@ Model routing allows you to route requests to different AI models based on wheth ::: - + ```ts import { Agent } from "agents-sdk" @@ -189,7 +189,7 @@ To use the AI SDK, install the `ai` package and use it within your Agent. The ex npm install ai @ai-sdk/openai ``` - + ```ts import { Agent } from "agents-sdk" @@ -216,7 +216,7 @@ Agents can call models across any service, including those that support the Open Agents can stream responses back over HTTP using Server Sent Events (SSE) from within an `onRequest` handler, or by using the native [WebSockets](/agents/examples/websockets/) API in your Agent to responses back to a client, which is especially useful for larger models that can take over 30+ seconds to reply. - + ```ts import { Agent } from "agents-sdk"