react-amphtml

Use [amphtml][amp repo] components inside your React apps easily!

Usage

react-amphtml exports React components and functions to easily create AMP HTML
pages. Each exported React component has a TypeScript interface and PropTypes
derived from AMP HTML's own validator rules to speed up development and make it
safer. Boilerplate and the inclusion of AMP directive-specific scripts is all
handled for you!

``js
// All AMP elements
import * as Amp from 'react-amphtml';

// Helper render props for actions and bindings
import * as AmpHelpers from 'react-amphtml/helpers';

// Components and functions to render pages
import {
AmpScripts,
AmpScriptsManager,
headerBoilerplate,
} from 'react-amphtml/setup';
`

$3

`js
import * as Amp from 'react-amphtml';
// ...

`

The main file exported by react-amphtml contains all of the AMP HTML
directives as React components. This includes the custom element amp-*
directives, normal HTML directives with validations required by AMP, and some
components with added functionality: Html, AmpState (amp-state directive)
and Script.

To see a list of available components and their relative documentation see the
official AMP components documentation: [The AMP component catalogue][].

[The AMP component catalogue]: https://amp.dev/documentation/components/

$3

`js
import * as Amp from 'react-amphtml';
import * as AmpHelpers from 'react-amphtml/helpers';

// Example of attaching actions to elements

{(props) => (

Do Something

)}


// Example of using state and bindings together
const defaultHeading = {
text: 'Hello, World!',
};
// ...

{defaultHeading}


{(props): ReactElement =>

{defaultHeading.text}

}

`

The helpers file contains render prop components that help add AMP attribute
directives for actions and bindings. Wondering what actions and bindings are all
about? Check out these official guides on the subjects:

* [Actions and events][]
* [Create interactive AMP pages][]

[Create interactive AMP pages]: https://amp.dev/documentation/guides-and-tutorials/develop/interactivity/
[Actions and events]: https://amp.dev/documentation/guides-and-tutorials/learn/amp-actions-and-events

$3

`js
import * as Amp from 'react-amphtml';
import {
AmpScripts,
AmpScriptsManager,
headerBoilerplate,
} from 'react-amphtml/setup';

const ampScripts = new AmpScripts();

const bodyContent = renderToStaticMarkup(



,
);

/ eslint-disable react/no-danger /
const html = renderToStaticMarkup(


{headerBoilerplate('/')}

{ampScripts.getScriptElements()}


,
);
/ eslint-enable /

const htmlPage =

${html}
;
`

The setup file makes creating pages for AMP HTML a breeze. It helps insert all
the necessary boilerplate and also the scripts needed for AMP directives.

The code is based on the requirements from AMP documented in
[Create your AMP HTML page: Required mark-up][].

[Create your AMP HTML page: Required mark-up]: https://amp.dev/documentation/guides-and-tutorials/start/create/basic_markup#required-mark-up

Examples

$3

Go checkout [ampreact][]!

If you are looking for an example that is in combination with one or more of
these tools:

* [AMP HTML][]
* [Next.js][]
* [React][]
* [styled-components][]
* [GraphQL][]
* [TypeScript][]

[ampreact][] gives a very nice setup to get started with or learn from!

[AMP HTML]: https://github.com/ampproject/amphtml/
[Next.js]: https://github.com/zeit/next.js/
[React]: https://github.com/facebook/react/
[styled-components]: https://github.com/styled-components/styled-components/
[GraphQL]: https://github.com/graphql/graphql-js
[TypeScript]: https://github.com/microsoft/TypeScript
[ampreact]: https://github.com/dfrankland/ampreact

$3

For simple usage examples of react-amphtml, check the Jest unit tests in
[react-amphtml/src/__tests__/react-amphtml.spec.tsx][]. The best test to look
at is can server-side render valid html for a good complete usage of
react-amphtml.

[react-amphtml/src/__tests__/react-amphtml.spec.tsx]: https://github.com/dfrankland/react-amphtml/blob/master/src/__tests__/react-amphtml.spec.tsx

Development

$3

The code for react-amphtml is generated from [AMP HTML's own validator][] via
[amphtml-validator-rules][].

Want to learn about AMP HTML validation? See the guide: [Validate AMP pages][].

Need to run the validator? Use either the online tool [The AMP Validator][] or
the npm package [amphtml-validator][].

[AMP HTML's own validator]: https://amp.dev/documentation/guides-and-tutorials/learn/validation-workflow/validate_amp
[Validate AMP pages]: https://github.com/ampproject/amphtml/tree/master/validator#amp-html--validator
[The AMP Validator]: https://validator.ampproject.org/
[amphtml-validator]: https://www.npmjs.com/package/amphtml-validator

$3

Use the following commands to develop on react-amphtml.

* npm run codegen: Create components based on AMP HTML's validator. This
must be done at least once prior to running npm run build, and can be done
afterwards anytime code in codegen is modified.

* npm run build: Bundles the source files into dist.

* npm run typecheck: Uses TypeScript to ensure type safety. Should be run
after running npm run build to check the files in dist that are bundled.

* npm run lint: Use ESLint to check source files.

* npm run test: Use Jest to run tests.

Resources

- [amphtml-validator-rules][]: the rules that get used to generate
components

- AMP Project's [amphtml repo][amp repo]

- [Builtins][]

- [Extensions][]

[amphtml-validator-rules`]: https://github.com/dfrankland/amphtml-validator-rules
[Builtins]: https://github.com/ampproject/amphtml/tree/master/builtins
[Extensions]: https://github.com/ampproject/amphtml/tree/master/extensions

[amp repo]: https://github.com/ampproject/amphtml