diff --git a/docs/builder/aws-lambda.mdx b/docs/guides/aws-lambda.mdx similarity index 99% rename from docs/builder/aws-lambda.mdx rename to docs/guides/aws-lambda.mdx index 5a3435f0e..af097f291 100644 --- a/docs/builder/aws-lambda.mdx +++ b/docs/guides/aws-lambda.mdx @@ -1,11 +1,9 @@ --- -slug: builder/aws-lambda +slug: aws-lambda title: AWS Lambda Builder description: Deploy a WAKU application to AWS. --- -# AWS Lambda Builder - The WAKU builder for AWS Lambda will provide the bundled output in the `dist` folder. The entry handler for the Lambda is `dist/serve-aws-lambda.handler`. diff --git a/docs/guides/cloudflare.mdx b/docs/guides/cloudflare.mdx index b0947ae5b..61952991a 100644 --- a/docs/guides/cloudflare.mdx +++ b/docs/guides/cloudflare.mdx @@ -1,5 +1,5 @@ --- -slug: guides/cloudflare +slug: cloudflare title: Run Waku on Cloudflare description: How to integrate Waku with Cloudflare Workers and interact with Cloudflare bindings and other resources. --- diff --git a/docs/guides/docker.mdx b/docs/guides/docker.mdx index 4e80ffb20..9add5809b 100644 --- a/docs/guides/docker.mdx +++ b/docs/guides/docker.mdx @@ -1,5 +1,5 @@ --- -slug: guides/docker +slug: docker title: Dockerise a Waku app description: How to package a Waku app into a Docker container. --- diff --git a/docs/tutorials/getting-started.mdx b/docs/guides/getting-started.mdx similarity index 87% rename from docs/tutorials/getting-started.mdx rename to docs/guides/getting-started.mdx index d03fed9e1..a421c7c3b 100644 --- a/docs/tutorials/getting-started.mdx +++ b/docs/guides/getting-started.mdx @@ -1,4 +1,8 @@ -# Chapter One +--- +slug: getting-started +title: Getting Started +description: Let's build with Waku! +--- ## Getting Started @@ -76,11 +80,11 @@ Either of these would render under the `/contact` route. **Layouts** are created with the special `_layout.tsx` filename and are how we create a shared layout that wraps a route and its descendents. -The layout at `/pages/_layout.tsx` is the [root layout](https://waku.gg/#root-layout), which wraps the entire site. Layouts can be nested as well, which we’ll see in later chapters. We’ll also discover **segment routes**, **nested segment routes**, and **catch-all routes** as well as Waku’s two rendering methods: **static prerendering** at build time and **dynamic rendering** at request time. +The layout at `/pages/_layout.tsx` is the [root layout](https://waku.gg/#root-layout), which wraps the entire site. Layouts can be nested as well, which we’ll see later. We’ll also discover **segment routes**, **nested segment routes**, and **catch-all routes** as well as Waku’s two rendering methods: **static prerendering** at build time and **dynamic rendering** at request time. ## And that’s all you need to get started -In the next chapters we’ll dive deeper into everything to understand how powerful, but simple Waku is! 🙂 +Soon, we’ll dive deeper into everything to understand how powerful, but simple Waku is! 🙂 --- diff --git a/docs/guides/monorepo.mdx b/docs/guides/monorepo.mdx index 64504409e..50438f06e 100644 --- a/docs/guides/monorepo.mdx +++ b/docs/guides/monorepo.mdx @@ -1,5 +1,5 @@ --- -slug: guides/monorepo +slug: monorepo title: Waku in a Monorepo Setup description: Tips for Using Waku in a Monorepo Setup --- diff --git a/docs/guides/react-compiler.mdx b/docs/guides/react-compiler.mdx index 3ceaac593..729ba2a70 100644 --- a/docs/guides/react-compiler.mdx +++ b/docs/guides/react-compiler.mdx @@ -1,5 +1,5 @@ --- -slug: guides/react-compiler +slug: react-compiler title: Enabling React Compiler in Waku description: Learn how to enable the React Compiler in your Waku project using the Vite Plugin to optimize your React applications. --- diff --git a/docs/guides/router-fetch-strategy.mdx b/docs/guides/router-fetch-strategy.mdx new file mode 100644 index 000000000..ec7d4dfea --- /dev/null +++ b/docs/guides/router-fetch-strategy.mdx @@ -0,0 +1,37 @@ +--- +slug: router-fetch-strategy +title: Waku Router Under the Hood +description: A brief look into the mechanics of the Waku Router +--- + +When routing around a waku app, you may notice some surprisingly quick navigation speeds. This was my experience while starting development at least. Let's walk through the basic mechanics of the router to get a better shared understanding of how it works and maybe even how to speed things up even further 🚀. + +## Power of Client-Side Caching + +Let's say you load into `/` first and there is a `` on the page. + +On initial load, the page from `pages/index.tsx` loads along with its route specific js bundle. As this loads, React does its hydration and we setup our RSC cache (we will revisit this later). + +Next, we press on the `/about` link and the router will fetch the RSC associated with the new page. Now that we are on the `/about` page and have read all about the project, we're ready to click the logo and navigate back to `/`. + +Here is where our first nice boost comes in! Since `/` is static, the client knows it can cache the RSC for this page, so we get our cache hit and immediately start rendering `/` without needing to go back to the server. + +## Speeding up Navigation with Dynamic Pages + +For dynamic pages, the expectation is that they should be re-requested from the server on each visit. So, links to a dynamic page will take the time that it takes for the server to render the page + the time spent over the network transmitting the RSC payload. This can make a navigation event to a dynamic page feel much slower. + +Fear not! We can take advantage of a very common trick for speeding the perceived load time of dynamic pages. + +```tsx + + Dynamic + +``` + +Now, when the user places their cursor over our link, we will fetch the RSC of that next page. Then when the user presses the link, if the promise for the RSC has resolved, we will switch to the next page, otherwise we will wait for the initial prefetch to finish. It's still a nice head start though! + +## Why is This Cool? + +None of this is specific to RSC, nor is it unique to Waku as a framework. However, the ergonomics of `prefetch` paired with the power of the client caching static RSC are quite nice features that will not be the default experience everywhere. + +We hope to cache only what is obviously cache-able with static RSC. Then we'll give you the tools to speed up your router interactions from there! diff --git a/docs/guides/stream-intercept.mdx b/docs/guides/stream-intercept.mdx index d57b1b048..629fa14f2 100644 --- a/docs/guides/stream-intercept.mdx +++ b/docs/guides/stream-intercept.mdx @@ -1,5 +1,5 @@ --- -slug: guides/stream-intercept +slug: stream-intercept title: SSR Stream Interception description: How to intercept SSR stream to inject content before it is sent to the client. --- diff --git a/packages/website/src/components/icon.tsx b/packages/website/src/components/icon.tsx index a92c1015e..64d3bd5a6 100644 --- a/packages/website/src/components/icon.tsx +++ b/packages/website/src/components/icon.tsx @@ -39,6 +39,24 @@ export const Icon = ({ icon, ...rest }: IconProps) => { ); + case 'guide': + return ( + + + + + ); default: return null; } diff --git a/packages/website/src/components/navigation.tsx b/packages/website/src/components/navigation.tsx index a9ef9cc4d..cc1840618 100644 --- a/packages/website/src/components/navigation.tsx +++ b/packages/website/src/components/navigation.tsx @@ -194,6 +194,7 @@ const docs = [ const links = [ { to: '/blog', icon: 'book', label: 'Blog' }, + { to: '/guides', icon: 'guide', label: 'Guides' }, { to: 'https://github.com/wakujs/waku', icon: 'github', label: 'GitHub' }, { to: 'https://discord.gg/MrQdmzd', icon: 'discord', label: 'Discord' }, ]; diff --git a/packages/website/src/components/post-list.tsx b/packages/website/src/components/post-list.tsx new file mode 100644 index 000000000..73fe27e66 --- /dev/null +++ b/packages/website/src/components/post-list.tsx @@ -0,0 +1,71 @@ +import { Link } from 'waku'; + +type PostListItemProps = { + slug: string; + title: string; + description: string; + author?: { + name: string; + }; + date?: string; + rawDate?: string; + release?: string | undefined; +}; + +const PostListItem = ({ + postItem, + path, +}: { + postItem: PostListItemProps; + path: 'blog' | 'guides'; +}) => ( +
  • + +
    + {postItem.release && ( +
    +
    + Waku{' '} + {postItem.release} +
    +
    + )} + {(!!postItem.date || !!postItem.author) && ( +
    + {!!postItem.date && {postItem.date}} + {!!postItem.date && !!postItem.author && ( + / + )} + {!!postItem.author && {postItem.author.name}} +
    + )} +
    +

    + {postItem.title} +

    +
    + {postItem.description} +
    + +
    • +); + +export const PostList = ({ + posts, + path, +}: { + posts: PostListItemProps[]; + path: 'blog' | 'guides'; +}) => ( + +); diff --git a/packages/website/src/components/post-page.tsx b/packages/website/src/components/post-page.tsx new file mode 100644 index 000000000..1e6e9ea09 --- /dev/null +++ b/packages/website/src/components/post-page.tsx @@ -0,0 +1,115 @@ +import { readFileSync } from 'node:fs'; +import { compileMDX } from 'next-mdx-remote/rsc'; +import { getFileName } from '../lib/get-file-name'; +import { components } from './mdx'; +import { getAuthor } from '../lib/get-author'; +import { Page } from './page'; +import { Meta } from './meta'; + +export async function PostPage({ + slug, + folder, +}: { + slug: string; + folder: string; +}) { + const fileName = await getFileName(folder, slug); + + if (!fileName) { + return null; + } + + const path = `${folder}/${fileName}`; + const source = readFileSync(path, 'utf8'); + const mdx = await compileMDX({ + source, + components, + options: { parseFrontmatter: true }, + }); + const { content } = mdx; + const frontmatter = mdx.frontmatter as { + slug: string; + title: string; + description: string; + date?: string; + author?: string; + release?: string; + }; + + const author = frontmatter.author ? getAuthor(frontmatter.author) : undefined; + const date = frontmatter.date + ? new Date(frontmatter.date).toLocaleDateString('en-US', { + month: 'long', + day: 'numeric', + year: 'numeric', + }) + : undefined; + + return ( + + +
    +
    + {frontmatter.release && ( +
    +
    + Waku{' '} + {frontmatter.release} +
    +
    + )} + {date && ( +
    + {date} +
    + )} +
    +

    + {frontmatter.title} +

    +

    + {frontmatter.description} +

    + {author && ( + +
    + +
    +
    + by {author.name} + , +
    + {author.biography} +
    +     + )} +
    +
    +
    + {content} +
    +
    + + star Waku on GitHub! + +
    +     + ); +} diff --git a/packages/website/src/lib/get-file-name.ts b/packages/website/src/lib/get-file-name.ts new file mode 100644 index 000000000..d1d800930 --- /dev/null +++ b/packages/website/src/lib/get-file-name.ts @@ -0,0 +1,52 @@ +import { compileMDX } from 'next-mdx-remote/rsc'; +import { readdirSync, readFileSync } from 'node:fs'; + +export const getFileName = async (folder: string, slug: string) => { + const blogFileNames: Array = []; + const blogSlugToFileName: Record = {}; + + readdirSync(folder).forEach((fileName) => { + if (fileName.endsWith('.mdx')) { + blogFileNames.push(fileName); + } + }); + + for await (const fileName of blogFileNames) { + const path = `${folder}/${fileName}`; + const source = readFileSync(path, 'utf8'); + const mdx = await compileMDX({ + source, + options: { parseFrontmatter: true }, + }); + const frontmatter = mdx.frontmatter as { slug: string }; + blogSlugToFileName[frontmatter.slug] = fileName; + } + + const fileName = blogSlugToFileName[slug]; + + return fileName; +}; + +export const getPostPaths = async (folder: string) => { + const blogPaths: Array = []; + const blogFileNames: Array = []; + + readdirSync(folder).forEach((fileName) => { + if (fileName.endsWith('.mdx')) { + blogFileNames.push(fileName); + } + }); + + for await (const fileName of blogFileNames) { + const path = `${folder}/${fileName}`; + const source = readFileSync(path, 'utf8'); + const mdx = await compileMDX({ + source, + options: { parseFrontmatter: true }, + }); + const frontmatter = mdx.frontmatter as { slug: string }; + blogPaths.push(frontmatter.slug); + } + + return blogPaths; +}; diff --git a/packages/website/src/pages/blog/[slug].tsx b/packages/website/src/pages/blog/[slug].tsx index d344328dc..60d2b010e 100644 --- a/packages/website/src/pages/blog/[slug].tsx +++ b/packages/website/src/pages/blog/[slug].tsx @@ -1,160 +1,19 @@ -import { readdirSync, readFileSync } from 'node:fs'; -import { compileMDX } from 'next-mdx-remote/rsc'; - -import { Page } from '../../components/page'; -import { Meta } from '../../components/meta'; -import { components } from '../../components/mdx'; -import { getAuthor } from '../../lib/get-author'; -import type { BlogFrontmatter } from '../../types'; +import { getPostPaths } from '../../lib/get-file-name'; +import { PostPage } from '../../components/post-page'; type BlogArticlePageProps = { slug: string; }; export default async function BlogArticlePage({ slug }: BlogArticlePageProps) { - const fileName = await getFileName(slug); - - if (!fileName) { - return null; - } - - const path = `./private/contents/${fileName}`; - const source = readFileSync(path, 'utf8'); - const mdx = await compileMDX({ - source, - components, - options: { parseFrontmatter: true }, - }); - const { content } = mdx; - const frontmatter = mdx.frontmatter as BlogFrontmatter; - - const author = getAuthor(frontmatter.author); - const date = new Date(frontmatter.date).toLocaleDateString('en-US', { - month: 'long', - day: 'numeric', - year: 'numeric', - }); - - return ( - - -
    -
    - {frontmatter.release && ( -
    -
    - Waku{' '} - {frontmatter.release} -
    -
    - )} -
    - {date} -
    -
    -

    - {frontmatter.title} -

    -

    - {frontmatter.description} -

    - -
    - -
    -
    - by {author.name} - , -
    - {author.biography} -
    -     -
    -
    -
    - {content} -
    - -     - ); + return ; } -const getFileName = async (slug: string) => { - const blogFileNames: Array = []; - const blogSlugToFileName: Record = {}; - - readdirSync('./private/contents').forEach((fileName) => { - if (fileName.endsWith('.mdx')) { - blogFileNames.push(fileName); - } - }); - - for await (const fileName of blogFileNames) { - const path = `./private/contents/${fileName}`; - const source = readFileSync(path, 'utf8'); - const mdx = await compileMDX({ - source, - options: { parseFrontmatter: true }, - }); - const frontmatter = mdx.frontmatter as BlogFrontmatter; - blogSlugToFileName[frontmatter.slug] = fileName; - } - - const fileName = blogSlugToFileName[slug]; - - return fileName; -}; - export const getConfig = async () => { - const blogPaths = await getBlogPaths(); + const blogPaths = await getPostPaths('./private/contents'); return { render: 'static', staticPaths: blogPaths, } as const; }; - -const getBlogPaths = async () => { - const blogPaths: Array = []; - const blogFileNames: Array = []; - - readdirSync('./private/contents').forEach((fileName) => { - if (fileName.endsWith('.mdx')) { - blogFileNames.push(fileName); - } - }); - - for await (const fileName of blogFileNames) { - const path = `./private/contents/${fileName}`; - const source = readFileSync(path, 'utf8'); - const mdx = await compileMDX({ - source, - options: { parseFrontmatter: true }, - }); - const frontmatter = mdx.frontmatter as BlogFrontmatter; - blogPaths.push(frontmatter.slug); - } - - return blogPaths; -}; diff --git a/packages/website/src/pages/blog/index.tsx b/packages/website/src/pages/blog/index.tsx index 040d8cf07..21696a58f 100644 --- a/packages/website/src/pages/blog/index.tsx +++ b/packages/website/src/pages/blog/index.tsx @@ -1,4 +1,3 @@ -import { Link } from 'waku'; import { readdirSync, readFileSync } from 'node:fs'; import { compileMDX } from 'next-mdx-remote/rsc'; @@ -6,6 +5,7 @@ import { Page } from '../../components/page'; import { Meta } from '../../components/meta'; import { getAuthor } from '../../lib/get-author'; import type { BlogFrontmatter } from '../../types'; +import { PostList } from '../../components/post-list'; export default async function BlogIndexPage() { const articles = await getArticles(); @@ -13,50 +13,22 @@ export default async function BlogIndexPage() { return ( -
    -
      - {articles.map((article) => ( -
    • - -
      - {article.release && ( -
      -
      - Waku{' '} - {article.release} -
      -
      - )} -
      - {article.date} - / - {article.author.name} -
      -
      -

      - {article.title} -

      -
      - {article.description} -
      - -
      • - ))} -
    -
    +     ); } const getArticles = async () => { const blogFileNames: Array = []; - const blogArticles: Array = []; + const blogArticles: Array<{ + slug: string; + title: string; + description: string; + author: { name: string }; + date: string; + rawDate: string; + release: string | undefined; + }> = []; readdirSync('./private/contents').forEach((fileName) => { if (fileName.endsWith('.mdx')) { diff --git a/packages/website/src/pages/guides/[slug].tsx b/packages/website/src/pages/guides/[slug].tsx new file mode 100644 index 000000000..72b9fe148 --- /dev/null +++ b/packages/website/src/pages/guides/[slug].tsx @@ -0,0 +1,19 @@ +import { getPostPaths } from '../../lib/get-file-name'; +import { PostPage } from '../../components/post-page'; + +type BlogArticlePageProps = { + slug: string; +}; + +export default async function BlogArticlePage({ slug }: BlogArticlePageProps) { + return ; +} + +export const getConfig = async () => { + const blogPaths = await getPostPaths('../../docs/guides'); + + return { + render: 'static', + staticPaths: blogPaths, + } as const; +}; diff --git a/packages/website/src/pages/guides/index.tsx b/packages/website/src/pages/guides/index.tsx new file mode 100644 index 000000000..4d56ac9d3 --- /dev/null +++ b/packages/website/src/pages/guides/index.tsx @@ -0,0 +1,69 @@ +import { readdirSync, readFileSync } from 'node:fs'; +import { compileMDX } from 'next-mdx-remote/rsc'; + +import { Page } from '../../components/page'; +import { Meta } from '../../components/meta'; +import type { BlogFrontmatter } from '../../types'; +import { PostList } from '../../components/post-list'; + +export default async function BlogIndexPage() { + const articles = await getArticles(); + + return ( + + +
    +

    + Our guides walk through hosting instructions, framework behavior, + developer tooling, and more! We will talk through unstable APIs here, + so you can help experiment with our new and fun features. +

    + +
    +     + ); +} + +const getArticles = async () => { + const blogFileNames: Array = []; + const blogArticles: Array<{ + slug: string; + title: string; + description: string; + }> = []; + + readdirSync('../../docs/guides/').forEach((fileName) => { + if (fileName.endsWith('.mdx')) { + blogFileNames.push(fileName); + } + }); + + for await (const fileName of blogFileNames) { + const path = `../../docs/guides/${fileName}`; + const source = readFileSync(path, 'utf8'); + const mdx = await compileMDX({ + source, + options: { parseFrontmatter: true }, + }); + const frontmatter = mdx.frontmatter as BlogFrontmatter; + + const article = { + slug: frontmatter.slug, + title: frontmatter.title, + description: frontmatter.description, + }; + + blogArticles.push(article); + } + + return blogArticles.sort((a, b) => a.slug.localeCompare(b.slug)); +}; + +export const getConfig = async () => { + return { + render: 'static', + } as const; +};