frontity

Overview

Apart from being the package that executes the Frontity commands in the terminal, frontity also exports functions, objects, etc. to be imported and used by other Frontity packages.

You can import any of these utils using:

import { connect, styled, Head, ... } from "frontity";

React

Use connect to inject state, actions and libraries in your React components.

Use the Headcomponent whenever you want to add HTML tags inside the <head> of any of your site's pages. You can read more Head in the Head page of our Learning Frontity section.

API reference:

CSS-in-JS

styledcreates new React components from HTML tags, or other React components, with styles attached to them. css lets you to add inline styles to an element if you don't want to create a new component. If you want to add styles for the whole app, use Global. And keyframes is used to define and use animations in your CSS.

You can read more in the Styles page of our Learning Frontity section.

API reference:

Code Splitting

Use loadable in order to separate you code into different bundles that will be dynamically loaded at runtime. This helps you to reduce your page size.

You can read more in the Code Splitting page of our Learning Frontity section.

API reference:

fetch and URL

Frontity exports fetch and URL with the same API they have in the browser, but working exactly the same both in the client and in the server.

API reference:

Helpers

API reference:

Api Reference

connect

Syntax

ConnectedComponent = connect(Component);

It's a function that receives a React component an returns the same component but connected to the Frontity state, actions and libraries. Any instance of that component will receive three new props: state, actions and libraries, allowing the component to read the state, manipulate it through actions or use any code other packages have exposed in libraries. Also, that instance will re-render automatically whenever the value of state which the component is using is changed.

Arguments

  • Component: a React component.

Return value

  • The same component but connected to state, actions and libraries.

Example

Page.js
import React from "react";
import { connect } from "connect";
import { Loading, List, Post, Page404 } from "./components";
โ€‹
const Page = ({ state }) => {
// The next line will trigger a re-render whenever
// the value of "state.router.link" changes.
const data = state.source.get(state.router.link);
return (
<>
{(data.isFetching && <Loading />) ||
(data.isArchive && <List />) ||
(data.isPostType && <Post />) ||
(data.is404 && <Page404 />)}
</>
);
};
โ€‹
// Connect Page to the Frontity state.
export default connect(Page);

โ€‹

styled

Syntax

// You can use an HTML tag like this.
const StyledDiv = styled.div`
font-size: 24px;
`;
โ€‹
// Or use it like a function and pass a React component.
const StyledComponent = styled(Component)`
background: aliceblue;
`;

It's a function that receives an HTML tag or a React component as argument and returns a function that can be used as a tagged template literal. Inside, you write the CSS code for your component. The tag function returns a styled component with the CSS you wrote. Also, styled has built-in tag functions for every HTML tag so in those cases it is not necessary to call styled directly.

Arguments

  • A template literal containing CSS code.

Return value

  • A React component with the styles defined.

Example

import { styled } from "frontity";
import { Page } from "./page";
โ€‹
const Main = () => (
<Container>
<StyledPage background="aliceblue" />
</Container>
);
โ€‹
const Container = styled.div`
display: flex;
justify-content: center;
`;
โ€‹
const StyledPage = styled(Page)`
background: ${props => props.background};
`;

โ€‹

css

Syntax

const styleObject = css`
background: pink;
`;

It's a tagged template literal to add inline style to React Components. The usage is quite similar to styled except that css doesn't return a React Component but a special object that can be passed to a component through the css prop.

Arguments

  • A template literal containing CSS code.

Return value

  • A style object to be passed to a css prop or to the <Global>'s styles prop.

Example

import { css } from "frontity";
โ€‹
const Component = () => (
<div css={css`background: pink;`}>
Styling my theme
</div>
);

โ€‹

Global

Syntax

<Global styles={styleObject} />

It's a React component that creates global styles for the whole Frontity site.

Using <Global> for other than html tags is not recommended because Frontity is not able to optimize it. That means you can use it for tags like html, body , a, img, and so on... but avoid it for classes. Use either the css prop or styled components instead.

Props

  • styles: an style object created with cssโ€‹

Example

import { Global, css } from "frontity";
โ€‹
const Page = () => (
<>
<Global
styles={css`
body {
margin: 0;
font-family: "Roboto";
}
`}
/>
<OtherContent />
</>
);

โ€‹

keyframes

Syntax

const animation = keyframes`
from { ... } to { ... };
`;

It's a function used to define and use animations in your CSS.

Arguments

Return value

  • An animation object to be used inside a template literal passed to styled or css.

Example

import { styled, keyframes } from "frontity";
โ€‹
// Create the keyframes.
const rotate = keyframes`
from {
transform: rotate(0deg);
}
to {
transform: rotate(360deg);
}
`;
โ€‹
// Add the animation to the styled component.
const Button = styled.button`
background-color: hotpink;
animation: ${rotate} 2s linear infinite;
`;
โ€‹
const Component = () => (
<Button>Styling my theme</Button>
);

โ€‹

loadable

Syntax

const HeavyComponent = loadable(importFunction, options);

It's a function that loads a component asynchronously generating a different bundle for it. Frontity has integrated and configured Loadable Components, in case you want to check its docs. You can also take a look at the Code Splitting page inside the Learning Frontity section.

Arguments

  • importFunction: a function that executes a dynamic import and returns a Promise that will contain the imported module.

  • options: an object with any of the following properties:

    • fallback: component displayed until the Promise resolves.

    • ssr: if false, it will not be processed server-side (default to true).

Return value

  • A React component.

Example

import { loadable } from "frontity";
import Content from "./components/content";
โ€‹
// Thanks to loadable we prevent comments from loading until it's needed.
const HeavyComments = loadable(() => import('./components/comments'));
โ€‹
const Post = ({ state }) => (
<>
<Content />
{state.comments.areOpened && <HeavyComments />}
</>
);
โ€‹
export default connect(Post);

โ€‹

Syntax

<Head>{children}</Head>

It's a React component that injects their children in the HTML <head> tag. It allows you to change the title while navigating, add meta tags, scripts, etc. As we use react-helmet under the hood, you may check its reference guide.

Props

  • children: the HTML tags you want to appear inside <head>.

Example

import { Head } from "frontity";
โ€‹
const Theme = () => (
<Head>
<title>My awesome blog</title>
<meta name="description" content="This blog is just for being awesome" />
<html lang="en" />
<link rel="canonical" href="https://example.com" />
</Head>
);

โ€‹

fetch

Syntax

const fetchResponsePromise = fetch(resource, init);

It's a function with the WHATWG API for fetching a resource from the network. This function is safe to use both server and client side, but you have to import it first.

Arguments

  • resource: a string containing the direct URL of the resource you want to fetch.

  • init: an options object containing any custom settings that you want to apply to the request (go to this link for the complete list of available settings).

Return value

  • A Promise that resolves to a Response object.

Example

import { fetch } from "frontity";
โ€‹
const getFromSomeAPI = async (resource) => {
const response = await fetch("https://site.com/api/v1" + resource);
const body = await response.json();
return body;
};

โ€‹

URL

Syntax

const url = new URL(url, base);

It's a constructor with the WHATWG API to create URLobjects. This constructor is safe to use both server and client side, but you have to import it first.

Arguments

  • url: a string representing an absolute or relative URL. If url is a relative URL, base is required.

  • base: a string representing the base URL to use in case url is a relative URL.

Return value

Example

import { URL } from "frontity";
โ€‹
const getApiPathname = ({ state }) => {
const { pathname } = new URL(state.source.api);
return pathname;
};

โ€‹

decode

An entity decoder that decodes HTML numeric entities and XML named entities. It works both in the server and the client and it's optimized to be both lightweight and performant.

Syntax

const decodedText = decode(text);

Arguments

  • text: a string representing the html to be escaped.

Return value

  • string

Example

import { decode } from "frontity";
โ€‹
const decodedText = decode("milk &amp; cookies");
โ€‹
console.log(decodedText); // "milk and cookies"