Add a live Instagram feed to Astro
Already have a static photo strip in InstaStrip.astro? Keep your layout and swap the hard-coded photos for live posts. We handle Instagram authorisation and token refresh; Astro renders the gallery.
You do not need an npm widget or a Meta developer app. Feedframer is a data API: unlimited API calls, no view metering, REST JSON, GraphQL and RSS. Free includes one account and six latest posts, updated daily. Premium is $6/month or $60/year, with up to five accounts, up to 100 posts per request and hourly updates.
1. Connect the Instagram account
Create a free account , connect an Instagram Business or Creator account, wait for the import to finish and copy its API key from the dashboard. The account owner must authorise the connection: typing a public username does not connect an arbitrary account. Personal Instagram accounts cannot be connected.
2. Set a server-side environment variable
Add this to your local .env and to your deployment platform's environment settings:
FEEDFRAMER_API_KEY=YOUR_API_KEY Keep .env out of Git. Do not use Astro's PUBLIC_ prefix or put the key in a browser script.
3. Replace the static grid in InstaStrip.astro
Create or update src/components/InstaStrip.astro with the following component. It uses the documented REST response: top-level posts, mediaType, mediaUrl, thumbnailUrl and permalink. A video needs its thumbnail, not its MP4 in an image tag. Posts without a displayable image are omitted.
---
type Post = {
id: string;
mediaType: 'IMAGE' | 'VIDEO' | 'CAROUSEL_ALBUM';
mediaUrl: string;
thumbnailUrl: string | null;
permalink: string;
altText?: string | null;
};
const apiKey = import.meta.env.FEEDFRAMER_API_KEY;
let posts: Post[] = [];
if (apiKey) {
try {
const url = new URL('https://feedframer.com/api/v1/me');
url.searchParams.set('api_key', apiKey);
const response = await fetch(url, { signal: AbortSignal.timeout(10000) });
if (!response.ok) throw new Error('Feed unavailable');
const feed = await response.json();
if (!Array.isArray(feed.posts)) throw new Error('Unexpected feed response');
posts = feed.posts.slice(0, 6);
if (feed.status === 'invalid_token') {
console.warn('Feedframer: reconnect Instagram in the dashboard. Showing stored posts.');
}
} catch {
// Do not log request URLs: they contain the account API key.
console.warn('Feedframer: unable to load Instagram posts.');
}
}
const tiles = posts.flatMap((post) => {
const src = post.mediaType === 'VIDEO' ? post.thumbnailUrl : post.mediaUrl;
return src ? [{ ...post, src }] : [];
});
---
<section aria-label="Latest Instagram posts">
{tiles.length > 0 ? (
<div class="instagram-grid">
{tiles.map((post) => (
<a href={post.permalink} target="_blank" rel="noopener noreferrer"
aria-label="View this post on Instagram">
<img src={post.src} alt={post.altText ?? ''}
width="400" height="400" loading="lazy" decoding="async" />
</a>
))}
</div>
) : <p>Our Instagram posts are temporarily unavailable.</p>}
</section>
<style>
.instagram-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 0.75rem; }
.instagram-grid img { display: block; width: 100%; height: auto; aspect-ratio: 1; object-fit: cover; }
@media (min-width: 48rem) { .instagram-grid { grid-template-columns: repeat(6, minmax(0, 1fr)); } }
</style>Use it from an Astro page:
---
import InstaStrip from '../components/InstaStrip.astro';
---
<InstaStrip /> If you already have styling, retain your grid classes and replace just the photo source with tiles. The sample shows a neutral unavailable message after a failed request; for production you may prefer your existing static images as a fallback. It does not implement a last-known-good cache or retries.
4. Make sure new posts actually reach the page
Static Astro: frontmatter runs during the build, not on every visit. The deployed HTML will not change simply because Instagram or Feedframer has new posts. Set up a scheduled rebuild on your hosting platform, daily for Free or hourly for Premium if that freshness matters. Add the API key to the build environment.
On-demand Astro: install the appropriate hosting adapter and disable prerendering on the page containing the strip (export const prerender = false), following the current Astro deployment guide. Do not put that export in the reusable component. Fetching then runs on the server at request time; configure page caching for your host. Feedframer's documented API edge cache is up to one hour, and Instagram imports are daily on Free or hourly on Premium. This is not a real-time Instagram webhook widget.
Feedframer or Behold for an Astro Instagram widget?
If you want a live Instagram widget that matches a custom Astro layout, Feedframer supplies JSON while you control the HTML and CSS. We do not meter API calls or website views, and Premium is $6/month. Behold also supplies JSON and has a no-code widget builder, which we do not offer. If you would rather configure a ready-made gallery than maintain a component, Behold can be the better fit. See the current comparison , including differences in refresh intervals and curation.
Troubleshooting
- Empty gallery: check the key is set on the host, the import has finished, and the account has posts.
- Feed never changes on a static site: check your rebuild schedule, not just the API response.
status: invalid_token: stored posts may still render, but the account owner must reconnect Instagram in the dashboard. Automatic token refresh cannot prevent every password change or revoked permission.- Videos missing: the grid needs a
thumbnailUrl. It deliberately skips videos without one. - Do not use
/api/v1/postsor a Bearer header. The endpoint is/api/v1/me?api_key=....