🗺️ v2 meta API

[chaance]

meta API for Remix v2

• Relevant issues
  • Meta function can't access loader data when it throws #3903
  • feat(remix-react): make actionData available in meta function #3534
  • An error in MetaFunction or LinkFunction is not caught by ErrorBoundary #3140
  • feat(remix-react): Add array-syntax for meta export #2598

Summary

This is a proposal for a new, more flexible API for route meta functions. Instead of returning an object with key/value pairings for a tag's name and content, the return signature for meta would look more like links, returning an array of objects expressing each tag's attribute values.

Additionally, this proposal will change how Remix handles meta in nested routes. When nested routes export a meta function, Remix will no longer automatically render meta tags from all matched routes in the tree. Routes will only render meta exported directly from the match itself, falling back to the most recent match only if meta is omitted from the leaf route.

Motivation

The meta API as designed is nice for a few reasons:

• The return signature tracks well with how most devs normally think about meta tags. <meta> is essentially a key/value pair, so returning an object that maps to rendered tags seems intuitive.

  export function meta() {
    return {
      // <meta name="description" content="Welcome to the web!" />
      description: "Welcome to the web!",
      // <meta name="theme-color" content="#f22" />
      "theme-color": "#f22",
    };
  }

• The key and value are generally provided via the name and content attributes respectively. But some tags use non-standard attributes. Tags that follow the OpenGraph protocol generally use property instead of name. These are hard to remember, so having Remix map them for you is a nice convenience.

  export function meta() {
    return {
      // <meta name="description" content="Welcome to the web!" />
      description: "Welcome to the web!",
      // Remix maps `og:url` to the property attribute in this case:
      // <meta property="theme-color" content="https://thebestwebsiteonplanetearth.lol" />
      "og:url": "https://thebestwebsiteonplanetearth.lol",
    };
  }

• We support a title value that maps to a <title> tag instead of <meta>, as the page title is still metadata. This means that updating the page title is as simple as updating any other page meta.

• With nested routing, you get the benefit of inheriting meta tags from parent routes. This is really nice if you only need to set one or two tags on a leaf node without a lot of duplication in a deeply nested route tree.

  // /app/routes/blog.tsx
  export function meta() {
    return {
      title: "Chance's Blog",
      "article:author": "Chance Strickland",
    };
  }
  
  // /app/routes/blog/$postId.tsx
  export function meta({ data }) {
    return {
      title: data.post.title,
      // The `article:author` tag is inherited from the parent
      // route but `title` is overridden. Remix merges these
      // objects for you,
    };
  }

While these features feel nice for most cases, Remix makes some assumptions about your app to implement them. These assumptions result in limitations with the API today:

• Meta tags should only have two attributes that map to a key and a value. Additional attributes cannot be passed to meta tags.

  <!-- good luck with this! -->
  <meta
    key="http-equiv:refresh"
    http-equiv="refresh"
    content="5;url=https://google.com"
  />

• We assume that our mapping of key/value pairs matches developer intent 100% of the time. It is impossible for you to tell us that you want to map to different attributes.

• Keys later in the tree will override matching keys higher up in the tree, which as an object-assignment should be expected. But what if you want to append to a key instead of overriding it (for example: array values for article:author tags)?

  // /app/routes/blog.tsx
  export function meta() {
    return {
      title: "Chance's Blog",
      "article:author": "Chance Strickland",
    };
  }
  
  // /app/routes/blog/$post.tsx
  export function meta({ data }) {
    if (data.guestAuthors?.length > 0) {
      return {
        title: data.post.title,
        // We might want to generate an `article:author` tag for
        // Chance as expressed in the parent route, but this will
        // override the parent route's value instead. We'd need access
        // to the parent's meta data here, which we don't have :(
        "article:author": data.guestAuthors.map((author) => author.name),
      };
    }
  }

• Meta tags in nested routes are always inherited, but what if you want a leaf route to opt out of rendering one or more meta tags from an ancestor route? We don't provide a way to do this today.

Opt-in

The proposed API constitutes a breaking change but will not be the default behavior in v1. The old API will continue to be the default behavior if developers take no action. Apps will opt-in to the new API with a feature flag in remix.config.js.

Detailed design

The new meta function would look like this:

export function meta({

  // the same thing you get from `useMatches`,
  // the most useful bits are the parent's data
  matches,

  // Errors that bubble up from the nearest
  // boundary will now be accessible.
  error,

  // params, location and data are unchanged
  params,
  location,
  data,
}) {
  if (error) {
    return [{ title: error.message || "Oh no!" }];
  }

  let { description, title } = data;
  return [
    // Each match node will have its meta objects
    // so that devs can still merge them if they want
    ...matches
      .map((match) => match.meta)
      .filter(filterTagsYouDontWantFromParentRoutes),
    { title },

    // Meta objects will declare the exact attributes
    // you want rather than Remix guessing for you
    { name: "description", content: description },
    { property: "og:description", content: description },
    { property: "og:image", content: "https://remix.run/logo.png" },
    { property: "og:type", content: "image/png" },
  ];
}

Return type signature

The return type signature of meta today looks like this:

// `meta` returns HtmlMetaDescriptor
export interface HtmlMetaDescriptor {
  charset?: "utf-8";
  charSet?: "utf-8";
  title?: string;
  [name: string]:
    | null
    | string
    | undefined
    | Record<string, string>
    | Array<Record<string, string> | string>;
}

The new type signature will look something like this (this is for explanation purposes at the moment and may need more complexity if we wish to provide any type checking for specific attributes like we do with links):

// `meta` v2 would return HtmlMetaDescriptor[]
export type HtmlMetaDescriptor =
  | ({ charset: "utf-8" } | { charSet: "utf-8" } | { title: string })
  | Record<string, string>;

Drawbacks

It's a lower-level API

The nice thing about the existing API is that it's simple, and you don't have to remember the API for deviations from the standard name/content attributes. This change would ask a bit more from developers, but we think the tradeoff is worth it given current limitations.

The good news is that we can adapt our existing code to provide a pretty straight-forward helper function that would help. We'd probably let the app own this code rather than expose it directly. After all, the whole point of this change is to give decisions about meta tags back to you.

objectToMetaArray(matches, {
  title: "Hello world",
  description: args.data.description,
  "og:image": "https://remix.run/logo.png",
});

We could also expose a helper for folks who want to use arrays for more granular control, but handles naive merging just as we do today.

mergeRouteMeta(matches, [
  { title: "Hello world" },
  { name: "description", content: args.data.description },
  { property: "og:image", content: "https://remix.run/logo.png" },
]);

Out of scope

There are other issues with meta that will still need to be resolved but are not in scope of this work:

• How to handle errors that are thrown while rendering <Meta /> #3140
• Accessing pending navigation information, pending submissions, and all the other stuff available to components but not to meta.

These issues will be addressed in later RFCs.

[kentcdodds]

I may be missing something, but with the new API, how would a child route override the document title specified by a parent route?

[ryanflorence]

Great idea. Like headers auto merging of cookies, we'll probably want to do a little bit of magic on title and only take the last one, maybe some other fields. Or we can keep it lower level in meta with no magic and provide a function that does some smart merging.

[donavon]

maybe provide a default merge function that would work for 90% of the cases, but allow it to be overridden for folks like me ;)

[chaance]

Or we can keep it lower level in meta with no magic and provide a function that does some smart merging.

I think this is the way to go. A helper function is easy to bail on or fork if it doesn't meet your needs.

[machour]

+1, magic is what got us here, let's avoid it at all costs this time

[ryanflorence]

Also note that usually you don't want meta on parent routes, use the index route instead. Then there's never any merging or overriding to worry about :)

[brookslybrand]

Big fan of this proposal! I just have a few comments, likely nothing super actionable (at least at this stage)

the return signature for meta would look more like links

I'm very happy about this! Personally, I remember finding it confusing that meta had a different signature than links (it honestly still trips me up if I haven't been in Remix world in a second). I like the consistency of API design, I think that's a really large plus for this change

The new type signature will look something like this (this is for explanation purposes at the moment and may need more complexity if we wish to provide any type checking for specific attributes like we do with links):

Regarding the return type signature, I would definitely recommend adding more type checking and specificity to the union. I think many TS users rely a lot on autocomplete with types to avoid them having to go to the docs 🙈

This change would ask a bit more from developers, but we think the tradeoff is worth it given current limitations.

True, but another way to say this is "with this API we're making better Web Developers, not better Remix Developers". I know it's a small thing to learn, but I do worry for new developers who come to Remix that they'll miss out a bit on how meta tags actually work and what all the attributes are. Requiring proper attributes to be supplied means developers will likely spend more time in the MDN docs than the Remix docs, because they'll be learning how meta tags work holistically. This means they can now more easily take their knowledge with them if they're ever unfortunate enough to not work in Remix.

Anyway, I know that's probably a small thing, just wanted to give a suggestion in terms of "messaging".

mergeRouteMeta

Big fan of exposing an API like this!

[chaance]

Regarding the return type signature, I would definitely recommend adding more type checking and specificity to the union. I think many TS users rely a lot on autocomplete with types to avoid them having to go to the docs 🙈

This is the intent. The actual type signature will be more complex and less readable, so the snippet here was more about communicating the change than precision.

[brookslybrand]

This is the intent. The actual type signature will be more complex and less readable, so the snippet here was more about communicating the change than precision.

Ah perfect! Thanks Chance, I think I just misunderstood what you had on that section. Keep up the great work!

[machour]

Speaking about types, we have this issue about meta parameters typing: #4451
Might be worth considering and including in the relevant issues section if it fits this RFC

[chaance]

Speaking about types, we have this issue about meta parameters typing: #4451 Might be worth considering and including in the relevant issues section if it fits this RFC

That's a great point. We are planning to add the error object, so probably good to account for that scenario moving forward.

[aaronadamsCA]

That's a great point. We are planning to add the error object, so probably good to account for that scenario moving forward.

Is this being tracked for v2? Sorry, I've searched everywhere but I can't find a thing.

I ask because now that #6107 and #6231 have been merged, IMO this is the one thing left blocking a "complete" implementation of this new API, as we'd probably like to be able to do more than just if (!data) return [{ title: "Error" }].

Ideally the shape would become something like { data: Data } | { error: Error } to make clear this is an either/or situation.

[tigerabrodi]

Meta tags in nested routes are always inherited, but what if you want a leaf route to opt out of rendering one or more meta tags from an ancestor route? We don't provide a way to do this today.

Makes sense why we'd want a lower-level API, cool to see! 🙏

I can see the motivation, even though I have never had this problem myself yet. 👍

[andrelandgraf]

I love this, especially the addition of the matches object!

mergeRouteMeta

I like the name, and it's probably convenient (especially for the migration from v1 to v2), but I am also okay with having a copy-paste version somewhere in the docs.

What would be a great value-add for me would be some autocompletion in VS Code (aka. typing) for some of the more popular meta tag names and properties, but I understand if this is out of scope or even messy.

[chaance]

Yes, I like this idea. The early types will be necessarily vague as there are some bigger issues we need to overcome to get proper loader data inference. Once that's resolved we'll come back and likely expand this a bit.

[tshddx]

Would this be the right place to mention the TypeScript type definitions of data in the meta function? I can't find any mention of this exact issue on GitHub or Discord.

The issue I'm having is that when I declare the type of the meta function as MetaFunction<typeof loader>, the data arg gets the inferred type just like useLoaderData<typeof loader>, but the meta function also gets called when loader throws and renders a CatchBoundary. TypeScript thinks data will always be defined, but in this case data will be undefined. This makes it very easy to cause a runtime error that prevents the 404 page from being rendered.

Here's a very simplistic example:

export const meta: MetaFunction<typeof loader> = ({ data }) => {
  // On a 404 page, `data` will be undefined, so this will throw a TypeError and
  // render an error page instead of the intended CatchBoundary 404 page.
  // The problem is that TypeScript thinks `data` will always be defined.
  return {
    title: data.name,
  };
};

export const loader = ({ params }: LoaderArgs) => {
  const blogPost = getBlogPost(params.id);
  if (!blogPost) {
    throw new Response('Not found', { status: 404 });
  }
  return json(blogPost);
};

export function CatchBoundary() {
  return <h1>Blog Post Not Found</h1>;
}

function getBlogPost(id?: string) {
  if (id === undefined || id === 'bad-blog-post-id') {
    return undefined;
  }
  return { id, name: `Cool post ${id}` };
}

I can work around this by discarding the MetaFunction<typeof loader> generic type and instead manually declare the type of data as SerializeFrom<typeof loader> | undefined. Now TypeScript will force me to check whether data is defined and thus prevent me from causing a runtime error. But perhaps it could be nice if the type of data inferred when using MetaFunction<typeof loader> was optionally undefined, so that I would be forced to check.

type LoaderData = SerializeFrom<typeof loader>;
export const meta = ({ data }: { data: LoaderData | undefined }) => {
  if (!data) {
    return { title: 'Blog Post Not Found' };
  }
  return { title: data.name };
};

[machour]

It have been mentioned in the discussion above and acknowledged 👍🏼

[ryanflorence]

Just came here to say the same thing! We should add better types to this while we're at it.

[ryanflorence]

Would need a generic for actionData types too: MetaFunction<typeof loader, typeof action>

[chaance]

@ryanflorence I think we discussed that adding action data would come in a later RFC, no?

[ryanflorence]

Yeah, I'd say let's fix the capability then enhance the types. @tshddx you want to add a proposal for better types here given the new signature @chaance is going to implement?

Oops read "actionData" as "types" 🙃 You're right, I forgot that's what we discussed :)

[xHomu]

Migrating my production app to v2_meta atm, looks like the matches prop isn't the same the object returned from useMatches() hook?

In v1_meta, the parentData prop provides access to all parent loader data.

In v2 meta, looks like matches only provide access to the parent metadata?

I could probably make it work for our purposes by regex the parent meta, but I can imagine this as a regression for some use-cases.

---

Edit: Realized that v2_meta still has access to parentData, matches is just a new addition on top of that, so my complaints are moot.

The available props should be mentioned in Remix Docs when it's updated!

[xHomu]

Is it intentional that every meta export in the entire routing tree is re-evaluated on every internal navigation?

Doesn't seem very useful now that meta no longer inherits from parent by default.

[sergiodxa]

You still need it to pass the previously matched meta to the child routes

[chaance]

Is it intentional that every meta export in the entire routing tree is re-evaluated on every internal navigation?

Doesn't seem very useful now that meta no longer inherits from parent by default.

Yes. This is mentioned in my original post and discusses the tradeoffs and rationale for dropping to a lower-level. You wrap your return value and the inherited meta with a helper function to get the exact same behavior by default.

[Mange]

I'm really exited about this new version! It's a great improvement.

Sadly, I got a bit disappointed when actually testing this out because I misunderstood something from the RFC:

  // the same thing you get from `useMatches`,
 // the most useful bits are the parent's data
 matches,

In the current implementation of this, the matches collection only contains information about the URL, not any data or handle fields from the loaders in the chain. At least not as far as I can tell either from the types or from the source code.

useMatches return a RouteMatch[], but the matches sent from V2Meta is RouteMatchWithMeta[], which sounds like a RouteMatch with extra meta information, but it's not.

This is RouteMatch that is used by useMatches:

export interface RouteMatch {
    id: string;
    pathname: string;
    params: Params<string>;
    data: RouteData;
    handle: undefined | {
        [key: string]: any;
    };
}

…and this is RouteMatchWithMetadata:

export interface RouteMatchWithMeta<Route> extends BaseRouteMatch<Route> {
    meta: V2_HtmlMetaDescriptor[];
}

// BaseRouteMatch is an alias to:
export interface RouteMatch<Route> {
    params: Params;
    pathname: string;
    route: Route;
}

Is this intentional? Will it change later?

---

I wanted to use this because I had a usecase where I could set the page title in one place in root by looking for the deepest data["$pageTitle"] in all child routes, instead of having to override meta in every single route in the entire project.

Something like this:

export const meta: V2_MetaFunction = ({ data, matches }) => {
  const appName = "Example App";

  // Hande data being possibly undefined due to an error somewhere.
  let title = data?.defaultPageTitle || appName;

  // Look for page titles in the whole route hierarchy. The last/deepest title wins.
  const titles = matches.map((match) => {
    const matchTitle = match.data["$pageTitle"];
    if (typeof matchTitle === "string" && matchTitle.length > 0) {
      return matchTitle;
    } else {
      return null;
    }
  }).filter(Boolean);

  if (titles.length > 0) {
    title = titles[title.length - 1];
  }

  return [
    {
      charset: "utf-8",
      viewport: "width=device-width,initial-scale=1",
      title
    },
  ];
};

Before in v1, I had to repeat this code in every single route that expose a $pageTitle (which is 90%+ of routes):

export const meta: MetaFunction<typeof loader> = ({ data }) =>
  setPageTitle(data);

(using a helper method that is imported that does similar logic to the first code example)

Title is set from the loader because I need A) i18n, and B) sometimes access to something inside the loaded data, like "Edit details for ".

[tom-sherman]

Just wanted to drop in to say that I Iove the idea of merged meta fields being an explicit thing.

This has tripped me up recently with headers. I had to reach for that API and expected it to work like meta, but of course it doesn't - headers requires the user to merge parent headers. Aligning these two APIs is a massive win for DX and learnability of the framework.

[58bits]

I took a stab at creating a mergeMeta helper function [pastes code and ducks]. I'm sure that anyone else in here that might be working on this will come up with something much better - but this got me most of the way there for now. And I completely ignore types - until the v1.10.0 release.

root.tsx

/**
 * meta
 * @returns V2_MetaFunction 
 * TODO: ts type for meta
 * New v2 meta api
 * https://github.com/remix-run/remix/releases/tag/remix%401.8.0
 * https://github.com/remix-run/remix/discussions/4462 
 * V2_MetaFunction interface is currently in v1.10.0-pre.5
 */
export const meta = ({ data }: any) => {
  return [
    { charset: 'utf-8' },
    { title: 'Remix Workbench App' },
    { name: 'description', content: 'A Remix demo app with CSS, Tailwind, Radix UI and other headless UI components.' },
    { name: 'viewport', content: 'width=device-width,initial-scale=1' },
    { name: 'theme-color', content: '#f59e0b' },
    { name: 'msapplication-TileColor', content: '#f59e0b' },
    { property: 'og:title', content: 'Remix Workbench App' },
    { property: 'og:description', content: 'A Remix demo app with CSS, Tailwind, Radix UI and other headless UI components.' },
    // Note - og:url will not update on route changes, but it should be fine for
    // og links being crawled or shared (i.e. a full SSR)
    { property: 'og:url', content: getUrl(data?.origin, data?.path) },
    { property: 'og:type', content: 'website' },
    { property: 'og:image', content: 'https://remix.infonomic.io/og.png' },
  ]
}

index.tsx

/**
 * meta
 * @returns V2_MetaFunction 
 * TODO: ts types for meta
 * New v2 meta api
 * https://github.com/remix-run/remix/releases/tag/remix%401.8.0
 * https://github.com/remix-run/remix/discussions/4462 
 * V2_MetaFunction interface is currently in v1.10.0-pre.5
 */
export const meta = ({ matches }: any) => {
  const title = 'Home - Remix Workbench App'
  return mergeMeta(matches,
    [
      { title },
      { property: 'og:title', content: title },
    ]
  )
}

utils.ts

/**
 * mergeMeta
 * @returns [] merged metatags
 * TODO: this is a temporary merge meta function for the 
 * new v2 meta api. It may not be complete or the best way 
 * to do this - but it works for the moment.
 * TODO: types
 * https://github.com/remix-run/remix/releases/tag/remix%401.8.0
 * https://github.com/remix-run/remix/discussions/4462 
 * V2_MetaFunction interface is currently in v1.10.0-pre.5
 */
export function mergeMeta(matches: any, tags: any[] = []) {
  function findMatch(upperTag: any, tag: any) {
    let found = false
    const rules = [
      { k: 'charSet', f: () => !!tag.charSet },
      { k: 'title', f: () => !!tag.title },
      { k: 'name', f: () => upperTag.name === tag.name },
      { k: 'property', f: () => upperTag.property === tag.property },
      { k: 'httpEquiv', f: () => upperTag.httpEquiv === tag.httpEquiv },
    ]

    for (let index = 0; index < rules.length; index += 1) {
      const rule = rules[index]
      if (upperTag[rule.k] !== undefined) {
        found = rule.f()
        break
      }
    }
    return found
  }

  const filteredMeta = matches.map((match: any) => match.meta)
    .map((upperTags: any[]) => {
      const filteredUpperTags: any[] = []
      for (const upperTag of upperTags) {
        let found = false
        for (const tag of tags) {
          found = findMatch(upperTag, tag)
          if (found) break
        }
        if (!found) filteredUpperTags.push(upperTag)
      }
      return filteredUpperTags
    })

  return [...filteredMeta, tags]
}

[sys13]

Few suggestions:

1. Example of using data, showing how it relates to Loader
2. Add types, or at least typeguards
3. Update the meta page to include this future v2 info

[58bits]

Here's an updated attempt at a mergeMeta utility function. I'd like to treat the root module meta tags as site-wide defaults, which can be replaced as needed by any route module.

/**
 * A utility function for the v2 meta API. It will
 * merge (filter) root metatags - replacing any that match
 * the supplied route module meta tags. It may not be complete 
 * or the best way to do this but it works for the moment.
 * https://github.com/remix-run/remix/releases/tag/remix%401.8.0
 * https://github.com/remix-run/remix/discussions/4462
 * 
 * @returns {V2_HtmlMetaDescriptor[]} Merged metatags
 */
export function mergeMeta(matches: any, tags: V2_HtmlMetaDescriptor[] = []): V2_HtmlMetaDescriptor[] {
  const rootModule = matches.find((match: any) => match.route.id === 'root')
  const rootMeta = rootModule.meta 

  function findMatch(rootTag: any, tag: any) {
    const rules = [
      { k: 'charSet', f: () => !!tag.charSet },
      { k: 'title', f: () => !!tag.title },
      { k: 'name', f: () => rootTag.name === tag.name },
      { k: 'property', f: () => rootTag.property === tag.property },
      { k: 'httpEquiv', f: () => rootTag.httpEquiv === tag.httpEquiv },
    ]

    for (const rule of rules) {
      if (rootTag[rule.k] !== undefined) {
        return rule.f()
      }
    }
    return false
  }

  if (rootMeta) {
    const filteredRootMeta = rootMeta
      .filter((rootTag: V2_HtmlMetaDescriptor) => {
        for (const tag of tags) {
          if (findMatch(rootTag, tag)) {
            return false
          }
        }
        return true
      })

    return [...filteredRootMeta, tags]
  } else {
    return tags
  }
}

which can be used in a route module as...

/**
 * meta
 * @returns {V2_MetaFunction}
 */
export const meta: V2_MetaFunction = ({ data, matches }): V2_HtmlMetaDescriptor[] => {
  const title = `Note - ${truncate(data?.note?.title, 50, true)} - Remix Workbench App`
  return mergeMeta(matches, [{ title }, { property: 'og:title', content: title }])
}

Thoughts or suggestions welcome.

[aaronadamsCA]

This might sound a bit weird at first, given Remix already has a links API, but I think it would make sense to add dynamic link support to this revised API, and just call it the Head API.

meta vs. links was never really the right API split, because Remix doesn't actually care about <meta> vs. <link>; AFAIK it only cares about stylesheet vs. not stylesheet. Remix needs stylesheets to be static links, but everything else - meta tags, canonical links, prev/next links - should be fine being dynamic, again AFAIK.

To build a canonical link, we absolutely need loader data. We can roll our own dynamic link API using handle, but this seems like something Remix should offer out of the box; and since dynamic links and v2 meta have the exact same "take data, render tag" requirement, it feels like it would make more sense as a single API.

[aaronadamsCA]

Thank you for shipping this improvement! We are now using it to add both canonical links and JSON-LD data, which is amazing.