{"id":9303,"date":"2026-04-17T08:18:19","date_gmt":"2026-04-17T13:18:19","guid":{"rendered":"https:\/\/frontendmasters.com\/blog\/?p=9303"},"modified":"2026-04-17T08:18:20","modified_gmt":"2026-04-17T13:18:20","slug":"building-a-blog-in-tanstack-part-1-of-2","status":"publish","type":"post","link":"https:\/\/frontendmasters.com\/blog\/building-a-blog-in-tanstack-part-1-of-2\/","title":{"rendered":"Building a Blog in TanStack (Part 1 of 2)"},"content":{"rendered":"\n

TanStack Start<\/a> is one of the newest web frameworks, and its popularity is rising quickly. Start is a thin server-side layer that sits atop TanStack Router and provides features like server functions, API endpoints, and server-side rendering. I wrote a three-part introduction to Router<\/a> and an introduction to Start<\/a>.<\/p>\n\n\n\n

This post will be a bit different. We’ll explore TanStack start via a more traditional, old-school use case: we’ll implement a blog (you can see the complete thing on GitHub<\/a>). It’s somewhat of a cliche, but it will let us explore important features, such as server functions and routing parameters, as well as niche patterns, such as static pre-rendering.<\/p>\n\n\n\n

Here in part 1, we’ll implement our blog. Then, in part 2, we’ll explore static generation in order to deploy it in the most sensible way. Stay tuned for that!<\/p>\n\n\n\n

Setting Up<\/h2>\n\n\n\n

We’ll write our blog posts in Markdown files and scan the appropriate directory to discover the posts we have, so we can generate links to them. Then, for the page that displays an individual blog post, we’ll parse the Markdown content and generate HTML with code highlighting.<\/p>\n\n\n\n

Finding the Posts<\/h3>\n\n\n\n

As a good first step, we’ll need to read all our blog posts. These posts are under the blog folder, in eponymous folders, each with an index.md<\/code>.<\/p>\n\n\n

\n
\"A<\/figure>\n<\/div>\n\n\n

We just want the names of these posts so we can generate links on our homepage. Vite actually has a nice import.meta.glob<\/code> method to read in all files in a dynamic way.<\/p>\n\n\n

const<\/span> allPosts: Record<string<\/span>, any<\/span>> = import<\/span>.meta.glob(\n  \"..\/blog\/**\/*.md\"<\/span>, \n  { query: \"?raw\"<\/span>, eager: true<\/span> }\n);<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
From there, we can inspect the URL of each .md<\/code> file we find and get the correct name. Here’s the entire method for this.<\/p>\n\n\n
export<\/span> const<\/span> getAllBlogPosts = ()<\/span> =><\/span> {\n  const<\/span> allPosts: Record<string<\/span>, any<\/span>> = import<\/span>.meta.glob(\"..\/blog\/**\/*.md\"<\/span>, { query: \"?raw\"<\/span>, eager: true<\/span> });\n\n  return<\/span> Object<\/span>.entries(allPosts).reduce(\n    (result<\/span>, [key<\/span>, module<\/span>]<\/span>) =><\/span> {\n      const<\/span> paths = key.split(\"\/\"<\/span>);\n      const<\/span> slug = paths.at(-2<\/span>)!;\n\n      result[slug] = module<\/span>.default<\/span>;\n      return<\/span> result;\n    },\n    {} as<\/span> Record<string<\/span>, string<\/span>>,\n  );\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Reading Metadata About Each Blog Post<\/h3>\n\n\n\n
We’ll use gray-matter<\/code><\/a> to read metadata from our blog posts.<\/p>\n\n\n
import<\/span> matter from<\/span> \"gray-matter\"<\/span>;<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
This will allow us to put metadata at the top of our Markdown blog files.<\/p>\n\n\n
---\ntitle: Post 1\ndate: \"2025-12-05T10:00:00.000Z\"\ndescription: Post 1\n---<\/span><\/code><\/span>Code language:<\/span> Markdown<\/span> (<\/span>markdown<\/span>)<\/span><\/small><\/pre>\n\n\n
From that, we can get the title, date, and description. We’ll whip up some types and helpers for this data.<\/p>\n\n\n
export<\/span> type<\/span> PostMetadata = {\n  title: string<\/span>;\n  date: string<\/span>;\n  description: string<\/span>;\n  slug: string<\/span>;\n  author: string<\/span>;\n  ogImage: string<\/span>;\n  coverImage: string<\/span>;\n};\n\nexport<\/span> type<\/span> Post = PostMetadata & {\n  content: string<\/span>;\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n
const<\/span> metadataFields: (keyof PostMetadata)[] = [\"title\"<\/span>, \"date\"<\/span>, \"description\"<\/span>, \"slug\"<\/span>, \"author\"<\/span>, \"ogImage\"<\/span>, \"coverImage\"<\/span>];\nconst<\/span> postFields: (keyof Post)[] = [...metadataFields, \"content\"<\/span>];<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
And a function to read the metadata for a single blog post.<\/p>\n\n\n
export<\/span> function<\/span> getPostMetadata<\/span>(slug: string, fileContents: string<\/span>): PostMetadata<\/span> <\/span>{\n  const<\/span> { data } = matter(fileContents);\n\n  const<\/span> result: PostMetadata = {\n    slug,\n  } as<\/span> PostMetadata;\n\n  \/\/ Ensure only the minimal needed data is exposed<\/span>\n  metadataFields.forEach(field<\/span> =><\/span> {\n    if<\/span> (typeof<\/span> data[field] !== \"undefined\"<\/span>) {\n      result[field] = data[field];\n    }\n  });\n\n  return<\/span> result;\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Building the Homepage<\/h2>\n\n\n\n
Let\u2019s build the main page for our blog. <\/p>\n\n\n\n
Here’s the route for our root index (\/) path. We’ve defined a loader, as well as specified the component we want rendered. The loader will\u00a0read the titles and metadata for each post. Then our component will render links for each.<\/p>\n\n\n
export<\/span> const<\/span> Route = createFileRoute(\"\/\"<\/span>)({\n  loader<\/span>: async<\/span> () => {\n    const<\/span> posts = await<\/span> getAllPosts();\n    return<\/span> {\n      posts,\n    };\n  },\n  component<\/span>: App,\n});<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Don’t let the boilerplate details here scare you. Even without AI, the standard TanStack file watcher that runs in dev mode will generate a minimal route object with the correct path whenever you add a new file in the routes folder.<\/p>\n\n\n\n
Our loader reads our posts. Then we connect up a React component for this route. Let’s look at each, in turn. <\/p>\n\n\n\n
If you’re thinking our loader can just call those utility methods we looked at before, well, not so fast. Those methods were reading file contents on disk. That’s all well and good, but in TanStack Start, our loaders are isomorphic. When you first browse to your website, that initial page will run its loader on the server, and the server will render your React component. Any subsequent time you browse to any page, that loader will run on the client, in your user’s browser. That means there’s no way we can run Node APIs to read file contents.<\/p>\n\n\n\n
This call below is a Server Function:<\/p>\n\n\n
const<\/span> posts = await<\/span> getAllPosts();<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Let’s look at its definition.<\/p>\n\n\n
const<\/span> getAllPosts = createServerFn().handler(async<\/span> () => {\n  const<\/span> postContentLookup = getAllBlogPosts();\n\n  const<\/span> blogPosts = Object<\/span>.entries(postContentLookup).map(([slug<\/span>, content<\/span>]<\/span>) =><\/span> getPostMetadata(slug, content));\n\n  const<\/span> allPosts: PostMetadata[] = blogPosts\n    \/\/ sort posts by date in descending order<\/span>\n    .sort((post1<\/span>, post2<\/span><\/span>) =><\/span> (post1.date > post2.date ? -1<\/span> : 1<\/span>));\n  return<\/span> allPosts;\n});<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
We get all the posts on disk, then read the metadata for each. This is a server function, so it will always run on the server, no matter where the route’s loader runs.<\/p>\n\n\n\n
Rendering the Blog Links<\/h3>\n\n\n\n
We won’t show the entire route component, but we will read the data from the loader.<\/p>\n\n\n
function<\/span> App<\/span>(<\/span>) <\/span>{\n  const<\/span> { posts } = Route.useLoaderData();<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Later, we’ll loop it and emit links for each blog post.<\/p>\n\n\n
<div>\n  {posts.map(post<\/span> =><\/span> (\n    <div key={post.title} className=\"blog-list-item\"<\/span>>\n      <h1>\n        <Link to={`\/blog\/$slug`<\/span>} params={{ slug: post.slug }}>\n          {post.title}\n        <\/Link>\n      <\/<\/span>h1>\n      <small>\n        <DateFormatter dateString={post.date}><\/DateFormatter>\n      <\/<\/span>small>\n      <p>{post.description}<\/p>\n    <\/<\/span>div>\n  ))}\n<\/div><\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
We can see it works! <\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Rendering Each Blog Post<\/h2>\n\n\n\n
Let’s get a route created to render an individual blog post. As the <Link><\/code> component from the homepage implied, we want our URLs of the form \/blog\/title-of-post<\/code>. Obviously title-of-post<\/code> is dynamic, so we’ll need a route variable. In TanStack, we do this by first creating a folder called blog<\/code> inside of our routes<\/code> folder, and then inside of that, we create a $slug.tsx<\/code> file.<\/p>\n\n\n\n
The dollar sign in front of $slug<\/code> means that $slug is actually a route parameter, which will be replaced with whatever is in the URL at that location.<\/p>\n\n\n\n
As before, the TanStack file watcher will scaffold a minimal route for us.<\/p>\n\n\n
import<\/span> { createFileRoute } from<\/span> \"@tanstack\/react-router\"<\/span>;\n\nexport<\/span> const<\/span> Route = createFileRoute(\"\/blog\/$slug\"<\/span>)({\n  component: RouteComponent,\n});\n\nfunction<\/span> RouteComponent<\/span>(<\/span>) <\/span>{\n  return<\/span> <div>Hello \"\/junk\/$slug\"<\/span>!<\/div>;\n}<\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Let’s fill it out with some details.<\/p>\n\n\n
export<\/span> const<\/span> Route = createFileRoute(\"\/blog\/$slug\"<\/span>)({\n  loader: async<\/span> ({ params }) => {\n    return<\/span> await<\/span> getPostContent({ data: { slug: params.slug } });\n  },\n  head: ({ params<\/span> }<\/span>) =><\/span> {\n    return<\/span> {\n      meta: [\n        {\n          title: `${params.slug}<\/span> | Adam Rackis's blog`<\/span>,\n        },\n      ],\n    };\n  },\n  component: RouteComponent,\n});<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
We add a loader that again calls a Server Function we’ll create in a moment. The loader takes a params object we can destructure, which contains the value of our path parameter, which we named $slug<\/code>. This was because our route was named $slug.tsx<\/code>.<\/p>\n\n\n\n
Then we have a head<\/code> function which allows us to set a title for this page (among other things), and like the loader, allows us access to the path params.<\/p>\n\n\n\n
Now let’s look at our server function that grabs our post’s content, for whatever slug we have in our url.<\/p>\n\n\n
export<\/span> const<\/span> getPostContent = createServerFn()\n  .inputValidator((data<\/span>: { slug<\/span>: string<\/span> }<\/span>) =><\/span> data)\n  .handler(async<\/span> ({ data }) => {\n    const<\/span> postContentLookup = getAllBlogPosts();\n\n    if<\/span> (!postContentLookup[data.slug]) {\n      throw<\/span> new<\/span> Error<\/span>(`Post not found: ${data.slug}<\/span>`<\/span>);\n    }\n\n    const<\/span> post = await<\/span> getPost(data.slug, postContentLookup[data.slug]);\n\n    return<\/span> { post };\n  });<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
We get the entire list of all blog posts, and verify that the one we want is in there. If it is, we call getPost<\/code> and return the result. Let’s take a look at getPost<\/code> now<\/p>\n\n\n
export<\/span> async<\/span> function<\/span> getPost<\/span>(slug: string<\/span>, fileContents: string<\/span><\/span>): Promise<\/span><Post<\/span>> <\/span>{\n  const<\/span> { data, content: markdownContent } = matter(fileContents);\n  const<\/span> content = await<\/span> markdownToHtml(markdownContent);\n\n  const<\/span> result: Post = {\n    slug,\n    content,\n  } as<\/span> Post;\n\n  \/\/ Ensure only the minimal needed data is exposed<\/span>\n  postFields.forEach(field<\/span> =><\/span> {\n    if<\/span> (typeof<\/span> data[field] !== \"undefined\"<\/span>) {\n      result[field] = data[field];\n    }\n  });\n\n  return<\/span> result;\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
The real work happens in markdownToHtml<\/code> which converts our Markdown to HTML.<\/p>\n\n\n\n
I decided to use markdown-it<\/a> along with Shiki<\/a>, but there are endless options out there. Here’s what it looks like.<\/p>\n\n\n
import<\/span> Shiki from<\/span> \"@shikijs\/markdown-it\"<\/span>;\nimport<\/span> MarkdownIt from<\/span> \"markdown-it\"<\/span>;\n\nconst<\/span> markdownIt = MarkdownIt({\n  html: true<\/span>,\n}).use(\n  await<\/span> Shiki({\n    themes: {\n      light: \"dark-plus\"<\/span>,\n      dark: \"dark-plus\"<\/span>,\n    },\n    transformers: [\n      {\n        name: \"line-numbers-pre\"<\/span>,\n        preprocess: (_: string<\/span>, options<\/span>: any<\/span><\/span>) =><\/span> {\n          if<\/span> (options?.meta?.__raw?.includes(\"line-numbers\"<\/span>)) {\n            options.attributes = {};\n            options.attributes.lineNumbers = true<\/span>;\n          }\n        },\n      },\n      {\n        name: \"line-numbers-post\"<\/span>,\n        postprocess: (html<\/span>, options<\/span>: any<\/span><\/span>) =><\/span> {\n          if<\/span> (options?.attributes?.lineNumbers) {\n            return<\/span> html.replace(\/<pre \/g<\/span>, \"<pre data-linenumbers \"<\/span>);\n          }\n          return<\/span> html;\n        },\n      },\n    ],\n  }),\n);\n\nexport<\/span> default<\/span> async<\/span> function<\/span> markdownToHtml<\/span>(markdown: string<\/span><\/span>) <\/span>{\n  return<\/span> markdownIt.render(markdown);\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
The vast majority of this setup was for a custom transformer that allows these special keywords after the triple backticks in Markdown.<\/p>\n\n\n
```<\/span>sql line-numbers\nSELECT id, SUM(amount)\nFROM some_table st\nJOIN other_table ot\nON st.id = ot.id\nWHERE active = true\nGROUP BY ot.id\n```<\/span><\/code><\/span>Code language:<\/span> Markdown<\/span> (<\/span>markdown<\/span>)<\/span><\/small><\/pre>\n\n\n
This then adds a data-linenumbers<\/code> attribute to the pre element<\/p>\n\n\n
<pre<\/span> data-linenumbers<\/span>=\"\"<\/span>><\/span><\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
And this attribute allows me to render line numbers via a CSS counter.<\/p>\n\n\n
pre<\/span>[data-linenumbers]<\/span> code<\/span> {\n  counter-reset<\/span>: step;\n  counter-increment<\/span>: step 0<\/span>;\n}\n\npre<\/span>[data-linenumbers]<\/span> code<\/span> .line<\/span>::before<\/span> {\n  content<\/span>: counter<\/span>(step);\n  counter-increment<\/span>: step;\n  width<\/span>: 1rem<\/span>;\n  margin-right<\/span>: 1rem<\/span>;\n  display<\/span>: inline-block;\n  text-align<\/span>: right;\n  color<\/span>: rgba<\/span>(115<\/span>, 138<\/span>, 148<\/span>, 0.4<\/span>);\n}<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
Now we can see our post.<\/p>\n\n\n
\n
\"\"<\/figure>\n<\/div>\n\n\n
And our line numbers work:<\/p>\n\n\n
\n
\"\"<\/figure>\n<\/div>\n\n\n
On to Part 2<\/h2>\n\n\n\n
Our blog is set up and working. In Part 2 (coming soon!), we’ll look at some simple tricks for deploying our blog as a static site with no server dependencies.<\/p>\n","protected":false},"excerpt":{"rendered":"
A site building framework like TanStack Start can be used to make a server-side rendered blog, no problemo. <\/p>\n","protected":false},"author":21,"featured_media":9345,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"sig_custom_text":"","sig_image_type":"featured-image","sig_custom_image":0,"sig_is_disabled":false,"inline_featured_image":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[1],"tags":[208,240],"class_list":["post-9303","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog-post","tag-blogging","tag-tanstack"],"acf":[],"jetpack_featured_media_url":"https:\/\/i0.wp.com\/frontendmasters.com\/blog\/wp-content\/uploads\/2026\/04\/tanstack-blog-1.jpg?fit=2000%2C1200&ssl=1","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/9303","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/users\/21"}],"replies":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/comments?post=9303"}],"version-history":[{"count":23,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/9303\/revisions"}],"predecessor-version":[{"id":9364,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/9303\/revisions\/9364"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/media\/9345"}],"wp:attachment":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/media?parent=9303"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/categories?post=9303"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/tags?post=9303"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
I previously blogged about CSS counters<\/a>, and of course, the complete code for this sample blog is on GitHub<\/a>.<\/p>\n\n\n\n
The solution is to use a Server Function. The docs\u00a0are here<\/a>, but the short version is that a TanStack Server Function is a function you define that always runs on the server. If you call a server function from a server-only location, such as an API endpoint, another server function, or even a route loader running on the server, TanStack will simply invoke it. And if you call a Server Function from the client, TanStack will do the legwork of firing off the correct network request.<\/p>\n\n\n\n