prismic-react-router
This repository serves as a boilerplate project to get started with a client-side Prismic site built with Create React App
Table of Contents
Background
When Scout started its first Prismic project, we found the resources around a React implementation to be quite scarce. As a result, we created several wrappers and utilities to make working with Prismic a bit more pleasant.
Usage
We highly recommend using a package manager and a bundler with this library. First, install the module:
# NPM 5+
npm i react react-dom react-router-dom prismic-javascript prismic-react-router
# NPM < 5
npm i --save react react-dom react-router-dom prismic-javascript prismic-react-router
# Yarn
yarn add react react-dom react-router-dom prismic-javascript prismic-react-router
Then, import based on your stack:
CommonJS
// import the entire package
const PrismicReactRouter = require('prismic-react-router');
// just a single module
const PrismicPage = require('prismic-react-router').PrismicPage;
ES Modules
// import the entire package
import * as PrismicReactRouter from 'prismic-react-router';
// just a single module
import { PrismicPage } from 'prismic-react-router';
UMD
If you're not using a bundler and would like a UMD build, no worries! We've got that too:
<script src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/react-router-dom/umd/react-router-dom.min.js"></script>
<script src="https://unpkg.com/prismic-javascript"></script>
<script src="https://unpkg.com/prismic-react-router@latest/dist/umd/prismic-react-router.js"></script>
<script>
var PrismicPage = window.PrismicReactRouter.PrismicPage;
</script>
API
PrismicPage(Page: React.Component, Loading: React.Component?, NotFound: React.Component?)
The PrismicPage component creates an easy-to-use wrapper around the Prismic API to fetch a single page. Rather than using the imperative API, the PrismicPage higher-order component provides a declarative way to fetch pages based on UID and access their content via props.
Props
prismicCtx: PrismicContext
- the Prismic API wrapperuid: string
- the UID of the page to fetch
Usage
class Home extends React.Component {
static pageType = 'home';
render() {
return this.props.err ? (
<h1>Error</h1>
) : (
PrismicReact.RichText.render(this.props.doc.data.content)
);
}
}
export default PrismicPage(Home, <h1>Not Found</h1>, <h1>Loading...</h1>);
// inside a react router component, likely
<PrismicPage prismicCtx={prismicCtx} uid="home" />;
<PrismicRoute />
The PrismicRoute component provides a convenient abstraction on top of react-router-dom
to automatically render Prismic pages based on route params.
Props
component: React.Component
- the component to Render for the given routecomponentProps: object
- the props to pass down to the rendered componentpath: string
- the path for react-router-dom to matchrouterProps: object
- the props passed in from the PrismicWrapper (documented below)
Usage
const Routes = props => (
<Router>
<Switch>
<PrismicRoute
path="/"
routerProps={props}
componentProps={{ uid: 'home' }} // pass in page UID if not in path
component={Home} // components should be of type PrismicPage
/>
<PrismicRoute
path="/blog/:uid" // uid path param is automatically detected
routerProps={props}
component={BlogPost}
/>
<Route component={NotFound} />
</Switch>
</Router>
);
<PrismicWrapper />
The PrismicWrapper provides a wrapper around the Prismic API for usage with PrismicRoute
s (documented above) and react-router-dom.
Props
routes: ReactRouterDom.Router
- the router configuration to wrapaccessToken: string?
- the access token for your repository, if neededrepositoryName: string
- the name of the Prismic repository to loadlinkResolver: (doc, ctx) => string
- a resolver to resolve Link components. see the Prismic documentation for more information
Usage
// using Routes from above example
ReactDOM.render(
<PrismicWrapper
routes={Routes}
repositoryName="scout-nu"
linkResolver={this.myResolver}
/>,
document.getElementById('root')
);
Maintainers
Adam Markon
Email: amarkon895@gmail.com
Twitter: @amarkon88
Code of Conduct
Scout strives to provide a welcoming, inclusive environment for all users, period. To hold ourselves accountable to that mission, Scout has a strictly-enforced code of conduct. Violating those rules will result in removal from the Scout organization, and potentially being banned from contributing to our projects.
Contributing
We welcome all contributions to our projects! Filing bugs, feature requests, code changes, docs changes, or anything else you'd like to contribute are all more than welcome! More information about contributing to Scout projects can be found in our contributors' guide!
License
All Scout libraries are ISC-licensed. tl;dr: you can use this code however you'd like, just please attribute us appropriately!
About Scout
Scout is Northeastern University's student-led design studio. The Studio has about 45 members selected via interview and application processes to select the university's best talent. Each semester the studio produces design and development assets for four ventures. Check out our portfolio for some past projects!