Make the backend URL a global setting

Description

The WordPress backend URL is only on state.source.api now, and it may (or may not) contain a prefix, usually /wp-json.

We have started to see more and more examples of different packages that need to know the WordPress URL, not only to access the REST API, but to other uses. Extracting the WordPress URL from state.source.api is not trivial.

Examples

  • Replace the URL of a link or a meta
    For example, changing links from https://wp.domain.com/my-link to https://www.domain.com/my-link for the @frontity/head-tags package.
  • Link or use a resource or asset that is stored in WordPress
    For example, linking to the RSS feed https://wp.domain.com/feed, sitemap https://wp.domain.com/sitemap.xml or service worker https://wp.domain.com/sw.js.
  • Other source packages could have different API urls
    If we stick with this approach and a package like @frontity/wpgraphql-source is released, it will break packages depending on state.source.api to get the WordPress URL.

I know we’ve seen more examples of this but I don’t remember them right now :sweat_smile:

Possible solution

Create a global setting for the backend, similar to state.frontity.url. Then, get rid of it on @frontity/wp-source, but keep the options that are relevant to the REST API.

export default {
  state: {
    frontity: {
      url: "https://mars.frontity.org",
      title: "Test Frontity Blog",
      description: "Useful content for Frontity development",
      backend: "https://test.frontity.org",
    },
  },
  packages: [
    {
      name: "@frontity/wp-source",
      state: {
        source: {
          prefix: "/wp-json", // This will be the default.
          prefix: false, // To use `?rest_route=`.
          isWpCom: true, // To support the WP.com API.
        },
      },
    },
  ],
};

This should be a backward-compatible change.

Drawbacks:

I guess there could be more than one backend for a single site.


@dev-team opinions?

Sounds good to me!

I cant think of any counterargument at the moment. Also, a side-effect would be that we can have zero-configuration for the wp-source package in that case :slight_smile:

I don’t like the name backend that much though because it’s quite generic… Maybe backendUrl or wordpressUrl …?

  • backend
  • backendUrl
  • wordpressUrl

0 voters

(edit the poll to add other suggestions if you like) :slightly_smiling_face:

I like the idea :slightly_smiling_face: Apart from being useful for the uses cases you listed, I think the settings would be clearer this way.

Does this change need to be backwards compatible?

Hey @nicholasio.oliveira

I’m afraid that yes. :slight_smile:

What use case do you have in mind that would require making it backwards-incompatible and in what way would it be incompatible?

I’m just thinking of packages and themes that potentially rely on state.source.api and therefore would break if we just remove it.

To make it backwards compatible state.source.api can be a derived state built with state.frontity.backend and state.source.prefix, so packages relying on state.source.api will still work:

const state = {
  source: {
    prefix: "/wp-json",
    api: ({ state }) => state.frontity.backend + state.source.prefix,
  },
};

If someone overwrites state.source.api in the frontity.settings.js file, it will still work because it will overwrite the derived state.


By the way, I wouldn’t name it wordpressUrl because now it’s going to be a global setting. Even though the framework (and the company) is focused on WordPress, there’s yet not a single line of the core hardcoded for WordPress and I would like it to remain that way. If someone else wants to start using Frontity for another CMS, they should be able to do so. All the WordPress integrations done so far and/or planned ahead are always done at a package level :slightly_smiling_face:

Looking at the results of the poll and taking into account that we should avoid the WordPress name in the core, I think we can go with backendUrl. And yes, as @mmczaplinski mentioned, this would make wp-source a zero-config package :smile: :tada:

const settings = {
  state: {
    frontity: {
      url: "https://mars.frontity.org",
      backendUrl: "https://test.frontity.org",
    },
  },
  packages: ["@frontity/wp-source"],
};

Thoughts?

2 Likes