Fetching data
We've made it easy for you to fetch the data and content you create with Outstatic by providing simple functions and APIs. You should use these on the front end of your Next.js website. They can be used as async functions in the /app
or /pages
directories.
Fetching collections
To fetch all your collections, without the documents, use the getCollections
function. It will return an array of strings, each string being the name of a folder under /outstatic/content/
.
Basic Document Fetching
Fetching all documents
To fetch all the documents from a collection, you can use the getDocuments
function as an async function when using the /app
directory or inside getStaticProps
or getServerSideProps
functions in the /pages
directory. The getDocuments
function accepts two parameters: the name of the collection as a string, and an array with the fields to be retrieved. It returns an array of Documents sorted by date, with the most recent publishedAt
documents first.
App directory example:
Pages directory example:
Fetching documents by slug
Documents can be fetched by slug, this is usually helpful when using Next.js' Dynamic Routes. The function getDocumentBySlug
takes three parameters: the name of the collection as a string, the slug of the document, and an array with the fields to be retrieved.
App directory example:
Pages directory example:
Keep in mind that the content is returned as Markdown. In order to convert it to HTML you should use a library such as remark. To see an example of how you can use remark to convert Markdown to html, please take a look at our Blog Example template.
Getting paths to use with getStaticPaths
or generateStaticParams
We provide a simple helper function so you can easily get all the document paths for a specific collection. This is helpful to feed the array of slugs needed for Next.js to statically generate dynamic routes.
Advanced Document Fetching - Metadata DB
Documents can also be retrieved with Outstatic's JSON database. Outstatic creates a metadata.json
file in the /outstatic/content
folder, where all the metadata for documents is stored. The load
method retrieves the JSON database, and you can then find()
documents matching either Outstatic properties such as publishedAt
and collection
, or any custom fields you've defined.
The Query Object
Querying for documents is done by passing an object in to find()
, containing a mongo-like query object. Under the hood, we use the excellent sift library which supports: $in, $nin, $exists, $gte, $gt, $lte, $lt, $eq, $ne, $mod, $all, $and, $or, $nor, $not, $size, $type, $regex, $where, and $elemMatch.
Requesting Fields
When retrieving documents, you can also specify one or more fields you'd like returned as part of the query, or call .project()
later on if you prefer a different syntax.
Sorting Results
Outstatic supports mongo-like sorting. When sorting, you can pass:
-
a string, which will sort the field ascending:
"title"
-
an object, where the key is the field to sort, and the value is
1
to sort ascending or-1
to sort decending:{title: 1}
-
an array containing a mix of the above two sorting options:
[{publishedAt: -1}, {title: 1}]
Skipping and Limiting
To support pagination, you may add a .skip(n)
or .limit(n)
to the API chain. The first will move through the results by n
entries, while the later ensures only a maximum of n
entries are returned.
Running the Query
Finally, once you've specified your query and any additional options, you can call toArray()
to return the matching documents. Up until now, all our API calls worked on the metadata JSON from outstatic. When you call toArray()
, Outstatic will retrieve your individual posts and return the set of documents inside of an array.
As a convienence, you can also call first()
instead, which returns the first result of the toArray()
call for you.
Advanced Fetch examples
Fetch a collection
Fetch by slug
Getting paths to use with getStaticPaths
or generateStaticParams
The load
method and find()
API can also be used for retrieving static paths. In these situations, it's recommended to retrieve as few fields as necessary for Next.js to build quickly.
Usage examples:
If you'd like to check out examples of how to use these functions, please refer to our Example Blog repository.