Watch Webinar: Figma - Design to Code in 80% Less Time

Announcing Visual Copilot - Figma to production in half the time

Builder.io logo
Talk to Us
Platform
Developers
Talk to Us

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

in beta

Builder's Qwik API is an performance-optimized alternative to the HTML API. It uses Qwik to prerender your content imto optimized HTML that requires no JavaScript to run, even if it has dynamic content.

Tip: The Qwik API has a limited set of features. If you want to build a Qwik app using Builder content, use the fully-featured Qwik SDK instead.

To experiment with the Qwik API, check out the Builder API Explorer, which works with your own Builder content.

The following is an example of a request and response:

https://cdn.builder.io/api/v1/qwik/YOUR_MODEL_NAME?apiKey=YOUR_API_KEY&url=PAGE_URL

# Example response
# {
#   "id": "c923kd89",
#   "name": "About page",
#   "data: {
#     "html": "<div data-builder-component="banner-ad"><div class="builder-blocks"><h1>Hello!</h1></div></builder-div>"
#   }
# }

Qwik is a framework designed for extremely fast site startup, which it achieves in two ways:

  1. Pure HTML delivery: Qwik delivers content in pure HTML, which is the fastest way to load content.
  2. Transparent lazy loading: Qwik lazy loads JavaScript behavior as needed, enhancing interactivity.

To integrate Qwik into your site, you need to perform two steps:

1. Integrate qwikloader.js by including the following script tag in your HTML:

<script async src="https://cdn.builder.io/js/qwik/qwikloader.js"></script>

The Qwik REST API delivers static HTML. So to make the HTML interactive, Qwik requires this small—less than 1kb—library.

2. Fetch your content. As an example, suppose you have a container, <div id="my-content"></div>, where you want to load the content. You'd use the following code snippet to fetch and inline the content into the HTML:

(async () => {
  const qwikUrl = 
        new URL('https://cdn.builder.io/api/v1/qwik/YOUR_MODEL_NAME');
  qwikUrl.searchParams.set('apiKey', 'YOUR_API_KEY');
  qwikUrl.searchParams.set('url', location.href);

  const response = await fetch(qwikURL);
  const { html } = await response.json();
  document.querySelector('#my-content').innerHTML = html;
})();

Repeat the above code for each content entry if multiple content entries need to be retrieved.

Qwik works best with Server-Side Rendering (SSR). You can cache the Qwik REST API response in a CDN and include it in your SSR content. Qwik automatically downloads additional JavaScript as needed for user interactions.

The following example, available in StackBlitz, uses the Qwik API to fetch content:

<html>
  <head>
    <script async src="https://cdn.builder.io/js/qwik/qwikloader.js"></script>
  </head>
<body>
  Add your header content as needed...
  <!-- The fetched Qwik content is rendered in the div below -->
  <div id="my-content"></div>
  Add your footer content as needed...

  <script>
    (async () => {
        const qwikUrl = new URL('https://cdn.builder.io/api/v1/qwik/page');
        // Demo API key for demonstration only. Replace with your Public API key
        qwikUrl.searchParams.set('apiKey', '5b8073f890b043be81574f96cfd1250b');
        qwikUrl.searchParams.set('userAttributes.urlPath', location.pathname);

        const response = await fetch(qwikUrl);
        const { html } = await response.json();
        document.querySelector('#my-content').innerHTML = html;
    })();
  </script>
</body>
</html>

The above example sets up a page using qwikloader.js and uses an async function that fetches the content which it then assigns to the #my-content div.

Inside the async function:

  • A URL object is created with the Qwik API endpoint URL.
  • Your Public API Key and user attributes, such as the URL path, are appended as query parameters to the URL.
  • The content is fetched from the Qwik API using fetch(), and the response is parsed as JSON.
  • The html property from the JSON response is extracted.
  • The extracted HTML content is rendered inside the <div> element with the id "my-content" using document.querySelector('#my-content').innerHTML = html;.

In this StackBlitz example, you can edit the code and use your own Public API Key. The following image is a screenshot of how this example renders in StackBlitz.

A screenshot of the code snippet above rendered in the browser. The content says: "Add your header content as needed...
This content comes from Builder.io.

Seeing this content verifies that you have correctly integrated with Builder.io.

NEXT STEP: Replace the apiKey with your key and start creating your own content.

Add your footer content as needed..."

To facilitate previewing a page during the creation process without the need for publishing or waiting for the CDN cache to update, you can add specific parameters to the Qwik URL. These parameters include:

  • includeUnpublished=true: This bypasses the cache and allows retrieval of unpublished content.
  • preview=true: This ensures that the latest version of the page is always returned.
  • overrides.page=: The can be found in the URL of the content you are editing in the Builder editor.

The following is an example of a URL that bypasses the cache and consistently provides the latest unpublished version:

...&includeUnpublished=true&preview=true&overrides.page=...
NameRequiredDescription

apiKey

Yes

Your API key

url

Yes

The current URL of the visitor on your site; for example:

?url=https://your-site.com/about?product=shirt

includeUnpublished

No

Set to true to include unpublished content in your API response; for example, for testing.

&includeUnpublished=true

query.*

No

MongoDB-style query of your data; for example:

&query.data.id=abc123
&query.data.myCustomField=someValue
&query.data.someNumber.$ne=20

fields

No

Only include these fields; for example:

&fields=id,name,data.customField

omit

No

Omit only these fields; for example:

&omit=data.bigField,data.blocks

userAttributes.*

No

Optionally use this to send targeting attributes; for example:

&userAttributes.device=desktop
&userAttributes.locale=en_us

cacheSeconds

No

Specify the duration, in seconds, for caching the content. This parameter sets the max-age value in the cache-control response header.

Increasing the value for better performance by caching the content for a longer period, while reducing the value is suitable for content that changes more frequently.

&cacheSeconds=120

If you need support for features that the beta Qwik API does not yet include—such as registering components, editing Builder content on the same URL as content served, A/B testing, insights and tracking—consider the Qwik SDK as an alternative.

As this API is in beta, we encourage you to share feedback in the Builder forum.

Was this article helpful?

Product

Visual CMS

Theme Studio for Shopify

Sign up

Login

Featured Integrations

React

Angular

Next.js

Gatsby

Get In Touch

Chat With Us

Twitter

Linkedin

Careers

© 2020 Builder.io, Inc.

Security

Privacy Policy

Terms of Service

Newsletter

Get the latest from Builder.io

By submitting, you agree to our Privacy Policy