@ykocaman/astro-medium-loader

An Astro loader that fetches and parses Medium RSS feeds by username. Supports canonical links, optional caching, and flexible storage strategies.

Installation

pnpm install @ykocaman/astro-medium-loader
# or
npm install @ykocaman/astro-medium-loader
# or
yarn add @ykocaman/astro-medium-loader

Usage

Import and configure the loader in your content.config.ts:

1. Live Fetching (Every Request)

Fetch and parse the user’s Medium posts on every build or request.

// content.config.ts
import { defineCollection } from 'astro:content';
import { mediumLoader } from '@ykocaman/astro-medium-loader';

const medium = defineCollection({
  loader: mediumLoader({
    username: 'ykocaman'
  })
});

export const collections = { medium };

2. Cached Fetching (Recommended for Development)

Cache the fetched feed under .astro/storage/medium to speed up repeated requests during development.

// content.config.ts
import { defineCollection } from 'astro:content';
import { mediumLoader } from '@ykocaman/astro-medium-loader';

const medium = defineCollection({
  loader: mediumLoader({
    username: 'ykocaman',
    storage: {
      enabled: true,
      path: '.astro/storage/medium'
    }
  })
});

export const collections = { medium };

Note: The .astro directory is typically git-ignored, so each new deploy will re-fetch the latest Medium posts.

3. Persistent Storage (Offline Builds)

Store the feed data permanently in a local directory (e.g. src/content/medium) so no further requests to Medium are needed after the initial build.

// content.config.ts
import { defineCollection } from 'astro:content';
import { mediumLoader } from '@ykocaman/astro-medium-loader';

const medium = defineCollection({
  loader: mediumLoader({
    username: 'ykocaman',
    storage: {
      enabled: true,
      path: 'src/content/medium'
    }
  })
});

export const collections = { medium };

Note: On the first build, the loader writes to src/content/medium/${username}.json. Subsequent builds read directly from that file.

4. Rendering Your Collection

Use Astro’s content API to retrieve and render your Medium posts just like any other collection:

---
import { type CollectionEntry, getCollection, render } from 'astro:content';
import BlogPost from '../../layouts/BlogPost.astro';

export async function getStaticPaths() {
	const posts = await getCollection('medium');
	return posts.map((post) => ({
		params: { slug: post.id },
		props: post,
	}));
}
type Props = CollectionEntry<'medium'>;

const post = Astro.props;
const { Content } = await render(post);
---

<BlogPost {...post.data}>
	<Content />
</BlogPost>

Options

Option	Type	Default	Description
username	string	—	Medium username (without the @)
storage.enabled	boolean	false	Enable caching or persistent storage
storage.path	string	.astro/storage/medium	Path to content directory (e.g. src/content/medium)

Features

• RSS Fetching & Parsing Automatically fetches and parses Medium RSS feeds.
• Canonical Links Injects a canonical link pointing back to the original Medium post.
• Flexible Caching Cache feed data in .astro for faster development builds.
• Persistent Content Storage Save feed output to your src/content directory for offline or CI-friendly builds.
• Full Astro Content Integration Works seamlessly with Astro’s default blog template, render and getCollection APIs.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License.