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/posts or a Bearer header. The endpoint is /api/v1/me?api_key=....

Starters and reference