Apollo Core

Apollo is a web component framework that uses global CSS (namespaced so that it should only style classes that start with xpl-). Under the hood, it uses Stencil to compile web components for various frameworks and Tailwind CSS for style utilities.

Installation

Apollo Core is published as a public package on NPM.

Install:

npm install @xplortech/apollo-core@latest

Styles

Apollo never injects stylesheets for you — import the CSS your app needs explicitly.

Recommended — brand variables plus shared component styles (swap apollo.css for field-edge.css or a custom variables sheet):

import '@xplortech/apollo-core/css/variables/apollo.css';
import '@xplortech/apollo-core/css/core.css';

Legacy alternative — single-file bundle (fully backwards compatible):

import '@xplortech/apollo-core/css/style.css';

Do not mix patterns. Use either style.css alone or the modular paths (variables/*.css, core.css, components/*.css) — never both.

For treeshaking, Field Edge, custom themes, and the full token contract, see the Theming & CSS docs and Core Required Tokens reference.

Other modular entry points: reset.css and tailwind-theme.css (both required when importing per-component components/*.css), typography.css (only needed when your own markup uses .xpl-text-* classes directly), and vendor/flatpickr.css.

Getting Started

Whether you use static HTML or a server-rendered framework (in Python, PHP, etc.), you can use Apollo Web Components in your markup. In the <head> of your document, include the CSS and JS:

<!--
NOTE: These paths assume that you serve your `node_modules` dir
along with your root directory. This is probably not the case for your app!
After you've downloaded Apollo, you can choose to serve these files from your
app's static directory.
-->

<link
  rel="stylesheet"
  href="./node_modules/@xplortech/apollo-core/build/variables/apollo.css"
/>
<link
  rel="stylesheet"
  href="./node_modules/@xplortech/apollo-core/build/core.css"
/>
<script type="module">
  import "./node_modules/@xplortech/apollo-core/dist/esm/apollo-core.js";
</script>

After including the CSS and JS, you can now begin using Apollo components in your app! Apollo supports rendering components by either using Web Components (custom elements) or vanilla HTML/CSS. If you opt for HTML/CSS, you will not have access to all the interactivity built into complex components, but you will have more fine-grained control over the rendering of components.

The pages for each component on the left include interactive embedded components which show the markup for both the Web Components and HTML/CSS versions. For example, for a basic button, you could use either the following Web Component or HTML/CSS display:

<xpl-button>Button Text</xpl-button>

<button class="xpl-button">Button Text</xpl-button>

Server-side rendering

Apollo Core includes a first-class SSR/hydration entry point published as @xplortech/apollo-core/hydrate:

import { renderToString, hydrateDocument } from '@xplortech/apollo-core/hydrate';

renderToString renders a static HTML string on the server, and hydrateDocument hydrates an already-serialized document in the browser. The React (@xplortech/apollo-react) and Vue (@xplortech/apollo-vue) wrappers leverage this entry point through their hydrateModule for framework-native SSR.

For Node, Next.js App Router, Nuxt, and Angular Universal setup — plus deterministic-render policy and the known-mismatch allowlist — see the Server-Side Rendering guide on the Apollo docs site.

To pass more complex data to a component, such as objects and arrays, you'll need to use javascript. For example, if you are rendering a xpl-table component, you need to add the data separate from the component markup:

<xpl-table></xpl-table>
<script>
  document.querySelector('xpl-table').data = [
    [
      "Row 1 Item 1",
      "Row 1 Item 2"
    ],
    [
      "Row 2 Item 1",
      "Row 2 Item 2"
    ]
  ];
</script>

Development Environment

Apollo includes a config file that extends VS Code's language support and intellisense functionality. To enable this support in your code, add the following to your local .vscode/settings.json file:

{
    ...,
    "html.customData": [
        "./node_modules/@xplortech/apollo-core/.typings/apollo-components.html-data.json"
    ]
}