frontity / api-reference

Frontity API Reference Documentation

📣 Frontity Framework is not actively maintained!

Frontity Framework is not under active development anymore. Pull requests and issues are not being actively reviewed. For more details, please see the blog post.

The team is now working on the WordPress Interactivity API. This will unblock the same UX Frontity framework enabled but directly in WordPress Core, fully compatible with the new Site Editor.

If you are interested in becoming a maintainer and continuing the development of the framework please do get in touch with one of the developers or let us know in this community thread.

Thanks!

The React Framework for WordPress

Frontity is the easiest way to create amazing websites using WordPress and React

Get started | Try demo in your browser | Learn Frontity

What is Frontity Framework?

Frontity is a free and open source framework for building WordPress websites based on React. It strips away the complexity that entails connecting both WordPress and React, and gives you a big head start by providing many of the most common queries already built in. In short, you can spend the bulk of your time on the development requirements of the project (e.g. the theme) and less time on setting up the project or worrying about tooling and configuration.

Frontity's unique approach, with its ease of use and extensibility pattern (similar to that of WordPress itself), offers distinct advantages over other similar React frameworks:

» It's 100% focused on WordPress

Each part of the framework has been simplified and optimized to be used with WordPress. This means the number of concepts that you as a developer need to learn are minimal. No complex configuration is necessary to get started, and the queries to the APIs that deliver the content are pre-configured for the things that developers most frequently need.

» It's opinionated

Frontity has its own state manager and CSS-in-JS solution. Thanks to that developers don't have to figure out how to configure these tools, or learn other technologies such as Redux or GraphQL.

» It's extensible like WordPress

Frontity powers a very flexible extensibility pattern similar to that of WordPress itself. To add new functionality or expand the capabilities of Frontity, you can use any of the existing Frontity and npm packages without having to build them from scratch.

Moreover, Frontity packages (including themes) can be activated and deactivated without code changes and are reusable across projects, helping reduce both development and maintenance times.

» It's rendered dynamically

In Frontity the HTML is rendered dynamically by a Node.js server or a serverless service. This means the HTML does not have to be rebuilt each time the content is edited or new content is published.

Because of its dynamic approach, Frontity provides a great power and reliability when it comes to frequent and real-time content updates, making it a great fit for those projects with content that might change rapidly or that is expected to grow over time.

See the About Frontity page in the docs to learn more. 🤓

How does Frontity work?

In a Frontity project, WordPress is used as a headless or decoupled CMS, just for managing the content. Frontity uses data from the WordPress REST API and generates the final HTML that is displayed in the browser using React.

With Frontity you still use your WordPress dashboard to edit and create content in exactly the same way that you are accustomed to. As you make changes content is automatically updated in your Frontity site, just as it is when using a traditional WordPress theme.

Frontity apps require both a Node.js server and a WordPress server (PHP) to run on. And there are two main Frontity Modes (architectures or configurations):

• Decoupled Mode
• Embedded Mode

Why a different Node.js server?

React is a JavaScript library. In order to generate HTML for site visitors or for Google, the server needs to be able to run JavaScript as well.

In theory a PHP server can send an empty HTML file with the JavaScript files included and the visitor will see the page after the JavaScript has loaded. However, this is not a good user experience and it is certainly not recommended if your site needs to be SEO friendly and to rank in search engine listings.

Frontity is prepared to be hosted either in a regular Node.js server or in serverless services. That makes it super cheap and infinitely scalable.

The Architecture page of the docs explains how Frontity works in detail. 🏗

Getting started

You'll need a WordPress installation and Node.js. See the Requirements page for more information.

If you can't wait to see what Frontity can do, head over to the Quick Start Guide.

If you're new to Frontity, we recommend that you check out the step-by-step tutorial, which will guide you through the fundamentals of building and deploying your first Frontity website.

Documentation

The Frontity documentation is distributed across three separate sites:

1. docs.frontity.org is the generic documentation. As well as theoretical information, such as Frontity Architecture and Core Concepts, you can find many practical guides here.
2. api.frontity.org is the API reference. This is where you can find detailed technical descriptions for the CLI, and for the packages and plugins available in Frontity Framework.
3. tutorial.frontity.org is the introductory step-by-step guide. It's designed to provide you with a deep and solid understanding of web development using Frontity.

More learning resources, such as videos and example projects, can be found in the Learn Frontity page. 📚

Community

For general help using Frontity, please refer to the documentation and the available learning resources. If you can't find an answer in these resources you can always check out the Frontity Community Forum, which is packed full of answers and solutions to all sorts of Frontity questions.

The community forum is a great place to ask questions, help fellow users build Frontity apps, and share your projects. It's also where you can keep track of the work done for the framework, join feature discussions, and collaborate on building Frontity itself.

Frontity is dedicated to a positive and inclusive community experience for everyone. Read through this guide to learn more about the forum guidelines, how it is organized, and how to get the most out of it.

Other channels

In addition to the community forum, Frontity has other channels where you can find out more information about the project, join in discussions about it, and also get involved:

• GitHub: for bug reports and code contributions.
• YouTube channel: learn from Frontity videos and playlists.
• Newsletter: designed to inform you about the latest product updates, learning resources and community news surrounding Frontity Framework.
• Twitter and the blog are also pretty good places if you're looking for news, case studies, and other updates.

Showcase

Want to know who's using Frontity? Need some inspiration for your project? The community is always building amazing projects with Frontity, discover some of them in the Showcase page.

Contributing

There are different ways to support the project and get involved. These are a few things that are always welcome:

• Testing new features
• Creating themes/packages and share them on npm or GitHub
• Creating educational content like blogs, videos, courses
• Improving the documentation
• Helping the community

See the Contributing section of the docs for more information on how to contribute. ✨

License

Frontity is licensed under the terms of the Apache 2.0 license.

api-reference's Issues

Add installation section for themes

Add an installation section for the two themes - @frontity/mars-theme and @frontity/twentytwenty-theme.

This is to provide installation instructions for a theme not chosen to be installed at the time that npx frontity create was run.

Similar to this.

Add docs to `wp-comments` package

• Code pull request: frontity/frontity#495 and frontity/frontity#521 frontity/frontity#542
• Feature Discussion: https://community.frontity.org/t/wordpress-comments-package/1267

The code PR contains the TSDoc which should be helpful in creating the documentation. You can refer to the README, as well.

The package implements the following API:

• state.comments.form - the state where the state of the comment submission form is held.
• state.source.comment - the state where the comments are stored after being fetched from the REST API.
• actions.comments.submit() - the action to submit a new comment to the WP REST API.
• actions.comments.updateFields() - the action that updates the fields of the form in state.comments.form.

Crucially, the package is currently in beta so we are not promising API stability until the package is 1.0.

Please note that the package requires the user to add a line configuration to their WP installation if they want to the package to work with anonymous comments (when the users are not logged in):

add_filter( 'rest_allow_anonymous_comments', '__return_true' );

The `error` and `warn` functions are missing in the `frontity` API docs

The frontity package exports an error and warn helpers to be used by package developers when they need to either throw an error or log a warn in the console.

None of them are yet documented in the frontity API section of our docs: https://docs.frontity.org/api-reference-1/frontity

I've added proper TSDocs for those functions in this PR: frontity/frontity#515

Please take into account that the code is in the @frontity/error package of our monorepo, but they should be imported using frontity by the packages, so they belong to the frontity API.

import { error, warn } from "frontity";

Examples of usage:

• https://github.com/frontity/frontity/blob/dev/packages/wp-source/src/actions.ts#L120
• https://github.com/frontity/frontity/blob/dev/packages/components/link.tsx#L82
• https://github.com/frontity/frontity/blob/dev/packages/components/switch.tsx#L29
• https://github.com/frontity/frontity/blob/dev/packages/frontity/src/utils/slot-and-fill/use-fills.tsx#L54

Broken links

Issues raised by @rmartinezduque

I've finished reviewing the API Reference docs (I'm not opening more PRs in this repo, I promise 😄), but I've noticed a few more links that are not working. I'm not sure where they should point to, so I prefer to share them here for you to review them:

In these pages the "Slot and Fill" links seem to be wrong (they point to https://docs.frontity.org/learning-frontity/roots#fills):

• https://api.frontity.org/frontity-packages/features-packages/smart-ads#settings
• https://api.frontity.org/frontity-packages/features-packages/smart-ads#object-properties
• https://api.frontity.org/frontity-packages/features-packages/smart-ads#using-the-slot-and-fill-pattern

The 'Tracking ID' link is not working here:

• https://api.frontity.org/frontity-packages/features-packages/analytics/comscore-analytics#settings

The "and enabled for pageviews" link is not working here:

• https://api.frontity.org/frontity-packages/features-packages/analytics/comscore-analytics#actions-analytics-pageview

[Packages] Add docs for the state populated by the Frontity core package

In the same fashion other packages do (e.g. @frontity/wp-source), the frontity package also exposes state that other packages may use.

The state properties and their description can be found in this file of the frontity monorepo: /packages/types/src/frontity.ts

Smart Ads package

We have created a new frontity package in the frontity monorepo which ads support for Smart Adserver

Feature Discussion: https://community.frontity.org/t/smart-adserver/1586/9
Pull Request: frontity/frontity#569

Brief overview

Smart Adserver is an ad serving network and they provide an API for displaying the ads which is described here

The @frontity/smart-adserver package will load a third-party Smart Adserver library which adds certain properties on the global window object. Then you as the developer can then use those properties to make the "ad call" (which are basically API calls to the Smart Adserver).

In response, the Smart Adserver dynamically loads some code which will modify the DOM to insert the ad in the place that was specified in the API call.

The package has 3 main components:

• The "Root" component. It includes the that loads the Smart Adserver library. When the user adds the @frontity/smart-adserver to their frontity.settings.js file, this will be loaded automatically.
• The SmartAd component. This component is exposed in libraries.fills.SmartAd. The users can just use this component directly to display ads by passing it relevant props. The component takes care of calling the Smart Adserver API and injecting the ad into the DOM in the relevant place
• Ability to specify the ads in fills in the frontity.settings.js file. Ads can be placed in specific slots in a theme by using that approach.

Source auth header and Frontity Query Options

wp-source now supports adding an Authorization header to requests to the REST API by adding it to state.source.auth!

Feature Discussion: https://community.frontity.org/t/support-for-auth-header-in-source-packages/2678/12

PR: frontity/frontity#568

The details of the feature are specified in the Feature Discussion, but I would like to point out all the changes that need to be documented here, because some of them are only tangentially related to the "auth header" feature:

1. The user can now use a state.source.auth property which holds the authentication information. This could be a JWT token or a Basic Authentication string, or something else. The user can pass a value to state.source.auth in multiple ways e.g. via frontity.settings.js or by setting it just like any other piece of frontity state.

   // frontity.settings.js
   const state = {
      source: {
       auth: "Basic YWFhOmJiYg",
     },
   };

   For security, the state.source.auth property is removed in the afterSSR() action, so that its value is not leaked to the client.

2. The timing of when the afterSSR() action is being called in frontity has changed. Now, it is called after the renderToString(jsx) has been called but before the state snapshot is taken and attached to the response that is then sent to the client. This has been changed in order to allow the removal of state.source.auth. in the afterSSR() action. This way if state.source.auth is present in the state on the server, it will not be sent to the client!

3. The value of the state.source.auth can be set via a query string. If a frontity_source_auth param is present in the url, state.source.auth will use its value.

4. The value of the state.source.auth can be set from an environmental variable. If frontity detects a FRONTITY_SOURCE_AUTH environmental variable, it will pass its value to state.source.auth. The value passed from the URL query string takes precedence over the value from the env variable.

5. libraries.api.source.get() now supports an (optional) auth parameter, which allows setting the Authorization header on the fetch() request:

   const response = await libraries.source.api.get({
     endpoint: "posts",
     params: { slug, _embed: true, ...state.source.params },
     auth: state.source.auth,  // This parameter is new !!! 
   });

6. The frontity_name and frontity_source_auth URL search params are removed from the initialLink and added to the new Options object on state.frontity.options.

   Note the parameters are camelCased when added to state.frontity.options, so they will have the format like state.frontity.options.frontityName and state.frontity.options.frontitySourceAuth even though the original URL params were frontity_name & frontity_source_auth.

   ⚠️ Important to note that from now on ALL search params that start with frontity_ will be removed from the URL and added to the options.

7. We have added support for loading environmental variables in frontity via .env files using the https://github.com/motdotla/dotenv/ package

Add documentation for `state.source.url`

Feature discussion: https://community.frontity.org/t/make-the-backend-url-a-global-setting/2381/20

Pull request: frontity/frontity#610

The pull request includes some details that are not relevant for conceptual understanding of this feature. The essentials are in the packages/wp-source/src/state.ts and packages/wp-source/types.ts

To give a brief overview:

1. Introduce a new property state.source.url in wp-source that points to the URL of the users' WordPress backend. The default value of that property is derived from state.frontity.url.

2. The default value of state.source.api  has changed. We now derive that value from the state.source.url. This should have no impact on existing applications, but has an important effect on new apps: You don't have to specify the state.source.api!

   You now can just specify the state.source.url and the state.source.api  is computed from it by adding the "prefix" (see point 3. 🙂 ).

3. Introduce a new property state.wpSource.prefix where the user can specify prefix of the REST API, for example "/wp-json" or "?rest_route=/". The default value is "/wp-json".

4. Introduce the state.wpSource.api and state.wpSource.isWpCom. For the moment their values are just derived from state.source.api and state.source.isWpCom respectively. This is added in preparation for the Source V2.

Client-side navigation for links found in the content

@nicholasio has created a new processor that replaces the anchor tags found in the HTML with the <Link> component.

The link component is now smarter and is capable of knowing if a link belongs to the source URL. If it does, it uses actions.router.set to do a client-side navigation. That new feature requires that the user has configured state.source.url, it won't work if the user is using state.source.api only, so that needs to appear in the docs.

He also added the processor to both mars-theme and twentytwenty-theme.

Explain how pageviews work with the `@frontity/google-tag-manager-analytics` package

Opening this issue because of this thread in the community: https://community.frontity.org/t/analytics-wont-track-pageviews/3813

It is true that, when using the @frontity/google-tag-manager-analytics package, you don't have to do anything more in Frontity (pageviews are sent automatically).

But, in order to send them to Google Analytics (or any other analytics service you may be using), you need to configure your GTM container to use a custom event called pageview, which has this format: https://community.frontity.org/t/google-tag-manager-package/1400/18

That's not explained neither in the docs nor in the package's README.

Document the Infinite Scroll hooks

• Pull Request: frontity/frontity#652
• FD's Final Implementation: https://community.frontity.org/t/infinite-scroll-hooks/2055/32

"Embedded Mode" documentation as WordPress plugin

Related conversation in the Community Forum → Documentation related to Embedded Mode (or Frontity PHP plugin)

WordPress Post Preview

Hey guys, we've added support for the ?preview=true query! 🎉

• FD: frontity/frontity#564
• PR: https://community.frontity.org/t/wordpress-preview-support/2419

This is related to the source auth option in the https://github.com/frontity/docs/issues/228 issue, so maybe it'd be a good idea to do it together.

That issue explains that now you can add a header to authenticate against the REST API.

This PR adds support for the ?preview=true query in the post type handlers that ship with wp-source. If they find the query, they use state.source.auth to authenticate and retrieve the last revision of a post. That way, when the user clicks on the preview button, the content that is shown is the content of the preview, like in WordPress.

We added a feature to the Embedded mode PoC to send a JWT in the ?frontity_source_auth query that ends up in state.source.auth, but that's not the only way to authenticate against the REST API to make the preview work. As long as you populate the state.source.auth with a valid Authorization header it will use that and it should work.

For example, it could work with these plugins:

• https://github.com/WP-API/jwt-auth
• https://github.com/WordPress/application-passwords

So I guess we should investigate other methods to make this work, apart from the Embedded mode PoC plugin.

Document the @frontity/[email protected]

There's a new major release for @frontity/google-analytics and it needs to be documented:

• PR frontity/frontity#733
• FD https://community.frontity.org/t/google-analytics-package/1084/19

Did I opened it up correctly? Please let me know if there's more info needed.

Add documentation for the Google Ad Manager package

The code PR: frontity/frontity#522

The PR only implements one component <GooglePublisherTag/> which is implemented according to the Feature Discussion

The main thing to be documented I think is how the user can:

1. Install the package npm i @frontity/google-ad-manager
2. Add and configure it in the frontity.settings.js like:

{
      name: "@frontity/google-ad-manager",
      state: {
        // Fills with ads.
        fills: {
          googleAdManager1: {
            slot: "Below Header",
            library: "googleAdManager.GooglePublisherTag",
            props: {
              unit: "/1234567/sports",
              size: [728, 90],
              id: "div-gpt-below-header",
            },
          },
        }
     }  
   }

Document the new "Frontity Slot Block" plugin and "slot-block" processor

• Final Implementation: https://community.frontity.org/t/frontity-slot-block/4534/4?u=luisherranz
• WordPress plugin: https://github.com/frontity/frontity-slot-block
• Processor PR: frontity/frontity#815

I was also wondering if it would be nice to have a Slot & Fill section in the Learning Frontity docs that explain the pattern. After all, it's one of the "core patterns". Perhaps the least known.

Also, maybe we should include some <Slot> components in mars-theme, so beginners know they exist. For example, we could add them before and after the post:

<Content>
  <!-- Add a Slot so other packages can add content here. -->
  <!-- https://docs.frontity.org/learning-frontity/slot-and-fills -->
  <Slot name="Before the post" />

  <!-- Use Html2React to process the HTML generated by WordPress -->
  <!-- https://api.frontity.org/frontity-packages/features-packages/html2react -->
  <Html2React html={post.content.rendered} />

  <!-- Add another Slot after the content. -->
  <Slot name="After the post" />
</Content>

What do you think?

Typo in libraries.source.parse() > return value section

Typo in libraries.source.parse() section.

Go to return value section:
Second return value "resultPath.parse()" description's value is "athname without the page" it should have a "P" like: "Pathname without the page"

Document type guards for Data objects and Entities

This is for documenting changes done in frontity/frontity#449 which are summarized here: https://community.frontity.org/t/extend-sources-data-interface-with-types-from-new-handlers/1187/38

Basically, it would be to add docs for those type guards and explain their purpose. Maybe we need to create a new page for @frontity/source package (types and type guards are included there).

In addition, the isTaxonomy conditional tag is deprecated and I guess we would have to fix some parts already documented in @frontity/wp-source.

Mention tiny-router's `autoFetch` in the `wp-source` docs

Hey guys, I was taking a look at the new wp-source docs. First of all, awesome work! 🙂

I think the explanation of how to use actions.source.fetch() in this section is perfect, but maybe we could add a small note or paragraph to note that, thanks to the state.router.autoFetch setting, people don't need to use useEffect + actions.source.fetch() when they use actions.router.set().

What do you think?

Document the new typed version of Mars Theme

Hey guys, we are about to release a typed version of mars-theme that @DAreRodz and I made during our last pair programming sessions:

• Code: https://github.com/frontity/frontity/tree/dev/packages/mars-theme-typescript
• PR: frontity/frontity#836

Any thoughts about how to reflect that in the docs? Should we use the same mars-theme docs, stating that there is a TypeScript version of it should have their own docs?

Add image and link processors

Add 'image' and 'link' processors to the list of default processors in html2react docs.

Write docs for the @frontity/yoast package

• Code Pull Request: frontity/frontity#548
• Feature discussion: https://community.frontity.org/t/support-for-yoast-plugin-rest-api-fields/2626

The documentation URL linked in the README file of the package is this one (it should be created, doesn't exist yet): https://docs.frontity.org/api-reference-1/frontity-yoast

This package has two options: transformLinks and onlyInSSR. Both are explained in theTSDocs written in types.ts.

wp-source with graphql

Final Implementation

Pull Request

Requirements

Functionalities

Out of Scope

API changes

Backward compatible changes

Breaking changes

Deprecated APIs

Technical explanation

Demo