Astro setup
Current supported frameworks
Section titled βCurrent supported frameworksβ- Alpine.js
- Angular
- Ember
- jQuery
- Lit
- Marko
- Preact
- Qwik
- React
- SolidJS
- Stencil
- Svelte
- Twig
- Vanilla JS
- Vue
Getting started
Section titled βGetting startedβRun the Create OutSystems Astro generator:
npx create-outsystems-astroSelect the framework(s) that you would like to include as part of your project.
This will create the generated files as well as an example component. You can delete the example component resources before starting on your project.
π Project Structure
Section titled βπ Project Structureβ/βββ src/β βββ framework/β βββ alpine/β βββ Counter.tsβ βββ angular/β βββ Counter.component.tsβ βββ ember/β βββ Counter.gtsβ βββ jquery/β βββ Counter.tsβ βββ lit/β βββ Counter.tsβ βββ marko/β βββ Counter.markoβ βββ preact/β βββ Counter.tsxβ βββ qwik/β βββ Counter.tsxβ βββ react/β βββ Counter.tsxβ βββ solid/β βββ Counter.tsxβ βββ stencil/β βββ Counter.tsxβ βββ svelte/β βββ Counter.svelteβ βββ vue/β βββ Counter.vueβ βββ images/β βββ image.pngβ βββ pages/β βββ alpine/β βββ alpine-counter.astroβ βββ angular/β βββ angular-counter.astroβ βββ ember/β βββ ember-counter.astroβ βββ jquery/β βββ jquery-counter.astroβ βββ lit/β βββ lit-counter.astroβ βββ marko/β βββ marko-counter.astroβ βββ preact/β βββ Counter.tsxβ βββ qwik/β βββ qwik-counter.astroβ βββ react/β βββ react-counter.astroβ βββ solid/β βββ solid-counter.astroβ βββ stencil/β βββ stencil-counter.astroβ βββ svelte/β βββ svelte-counter.astroβ βββ vue/β βββ vue-counter.astroβ βββ styles/β βββ index.cssβββ package.jsonIt is recommended not to mix different frameworks on a single Astro page (.astro file) page. Having multiple Astro islands on an OutSystems page should be fine.
For Angular, keep the framework/angular structure in place or update the astro.config.mjs fileβs transformFilter section. This is the location that Astro will use to modify the Angular files.
Each page inside of the pages file should represent an Island that will be imported into OutSystems. The example has them separated by framework name, but you can name them anything you would like. The output script will flatten the index.html to the root of the output folder with the name of the folder.
Client loading
Section titled βClient loadingβFor any of the official frameworks (react, preact, solid-js, vue and svelte) you should pass client:only=β[FRAMEWORK]β. See Astro documentation for client:only. For other fameworks, such as Angular, it should pass client:load or any other non specific famework.
Qwik takes either client:load, which keeps server rendering and lets Qwik resume the container it emitted, or client:only="@qwik.dev/astro", which renders it entirely on the client like the other JSX frameworks. See the Qwik integration guide.
Alpine.js takes client:load. Its renderer returns no server markup, so the island is rendered entirely on the client. See the Alpine.js integration guide.
Ember takes client:only="ember-astro", the name the ember-astro renderer registers. client:only="ember" fails with a missing hint error. See the ember-astro documentation.
jQuery takes client:load. Its renderer returns no server markup, so the component renders into the island entirely on the client. See the jQuery integration guide.
Lit takes client:load. Its renderer returns no server markup, so the element is created entirely on the client. See the Lit integration guide.
Marko takes client:load. Its renderer returns no server markup, so the template is mounted entirely on the client. See the Marko integration guide.
Stencil takes client:load. Its renderer returns no server markup, so the element is created entirely on the client. See the Stencil integration guide.
Framework
Section titled βFrameworkβThe location of the component code.
JSX frameworks
Section titled βJSX frameworksβFor JSX based frameworks, you must use the jsxImportSource header at the top of the page:
/** @jsxImportSource preact *//** @jsxImportSource @qwik.dev/core *//** @jsxImportSource react */SolidJS
Section titled βSolidJSβ/** @jsxImportSource solid-js */Stencil
Section titled βStencilβ/** @jsxImportSource @stencil/core */Any image assets.
Stylesheets that may apply to the component.
π§ Commands
Section titled βπ§ CommandsβAll commands are run from the root of the project, from a terminal, based on your package manager:
| Command | Action |
|---|---|
npm install |
Installs dependencies |
npm run dev |
Starts local dev server at localhost:4321 |
npm run build |
Build distribution to ./dist/ |
npm run output |
Build OutSystems production site to ./output/ |
npm run preview |
Preview build locally, before creating output |
npm run astro ... |
Run CLI commands like astro add, astro check |
npm run astro -- --help |
Get help using the Astro CLI |
Parameters
Section titled βParametersβSince OutSystems does not have a concept of NULL, you may have to code around NULL/undefined in your library.
Slots are an optional HTML that can be passed into a component. They are then able to be picked up and used by the Astro Island component. You can use either default slot or named slots (or both).
Angular
Section titled βAngularβAngular does not support the use of slots.
Astro passes slots to an Ember component as HTML strings in the @slots argument, keyed by slot name, and passes the props in @props. Insert a slot with triple curlies so it is not escaped. See slots in ember-astro.
- Astro example:
<CounterComponent client:only="ember-astro"> <div slot="header"> <p>Slot header</p> </div> <div> <p>Slot content</p> </div> </CounterComponent>- Ember example:
<template> {{{@slots.header}}} <div> {{{@slots.default}}} </div> </template>The default slot (no name) will go into a Preact component as the children prop name. A named slot will go in as a parameter with the name.
- Astro example:
<CounterComponent client:only="preact"> <div slot="header"> <p>Slot header</p> </div> <div> <p>Slot content</p> </div> </CounterComponent>- Preact example:
export default function Component({ children, header, }: { children: ComponentChildren header: ComponentChildren; }) { return ( <> {header} <div> {children} </div> </> ); }The default slot (no name) will go into a React component as the children prop name. A named slot will go in as a parameter with the name.
- Astro example:
<CounterComponent client:only="react"> <div slot="header"> <p>Slot header</p> </div> <div> <p>Slot content</p> </div> </CounterComponent>- React example:
export default function Component({ children, header, }: { children: React.ReactNode; header: React.ReactNode; }) { return ( <> {header} <div> {children} </div> </> ); }The default slot (no name) will go into a Preact component as the children prop name. A named slot will go in as a parameter with the name.
- Astro example:
<CounterComponent client:only="solid-js"> <div slot="header"> <p>Slot header</p> </div> <div> <p>Slot content</p> </div> </CounterComponent>- React example:
export default function Component({ children, header, }: { children: JSX.Element; header: JSX.Element; }) { return ( <> {header} <div> {children} </div> </> ); }The default slot (no name) will go into a Svelte component as the <slot> name. A named slot will go in as a parameter with the name.
- Astro example:
<CounterComponent client:only="svelte"> <div slot="header"> <p>Slot header</p> </div> <div> <p>Slot content</p> </div> </CounterComponent>- Svelte example:
<slot name="header" /><div> <slot /></div>The default slot (no name) will go into a Vue component as the <slot /> name. A named slot will go in as a parameter with the name.
- Astro example:
<CounterComponent client:only="react"> <div slot="header"> <p>Slot header</p> </div> <div> <p>Slot content</p> </div> </CounterComponent>- Vue example:
<template> <slot name="header" /> <div> <slot /> </div> </template>Using OutSystems handlers
Section titled βUsing OutSystems handlersβSince OutSystems cannot pass in a function handler, it has to be bound to the window object. Usually, this is passed in as a name, and that name is a handler for the window function. On the Astro library side, you have to call the following (replace functionName):
window[functionName](value);To pass back an array or object, you must JSON.stringify it first. The object must then be deserialized on the OutSystems side.
window[onSelectChange](JSON.stringify(newValues));You cannot send Union types (such as either an array or object) due to OutSystems being strongly typed. For example, if you have instances where you send either 0, 1 or multiple items back to the handler, it is important to have an array for that. If only expecting 0-1 items, an object should be fine.
Converting to OutSystems
Section titled βConverting to OutSystemsβ-
Copy the environment template file to
.env.Terminal window cp .env.template .env -
Update the
.envfile and modify theASSET_PATHvalue to be the application/library/core widget module name in OutSystems. -
Once development is complete, run:
Terminal window npm run output
This will create a set of files that will then need to be converted to OutSystems components.
It also creates output/resources.txt, the list of the OutSystems resource URLs for every file in output/assets. Paste it into the assign before the Deploy Resource action so all of the resources are deployed. See Deploy JavaScript files to target for O11 or ODC.
If using a directive for the component of anything other than client:only, you may need to delete the interior contents of the rendered island (since it will have done some static generation).
Testing
Section titled βTestingβThe generator comes with unit, integration and testing built in. You can use the built in ones or replace them with your own testing framework preferences.
Unit testing
Section titled βUnit testingβ- Vitest
The unit tests are placed in the
test/unitfolder. This is primarily for testing functions and logic.
Integration Testing
Section titled βIntegration Testingβ- Angular Testing Library
- DOM Testing Library
- Preact Testing Library
- Qwik testing helpers (
createDOMfrom@qwik.dev/core/testing) - React Testing Library
- SolidJS Testing Library
- Svelte Testing Library
- Vue Testing Library
The integration tests are placed in the test/integration folder. This tests the interaction between the components as a whole.
End-to-End
Section titled βEnd-to-Endβ- Playwright
The end-to-end tests are placed in the
test/e2efolder. This tests build the project and then runs a server preview. Playwright will launch a browser and test the page and components. To get started, install the Playwright browsers and necessary dependencies.
| Command | Action |
|---|---|
npm run test |
Run unit and integration tests |
npm run test:e2e:install |
Install Playwright browsers and dependencies |
npm run test:e2e |
Run the end-to-end tests |
npm run test:e2e:ui |
Run the end-to-end tests in UI mode |
- Prettier
Formatting sets the guidelines for the code styles. The rules are able to be updated in the
.prettierrcfile.
| Command | Action |
|---|---|
npm run format |
Run format check |
npm run format:write |
Run format check and fix issues |
- ESLint
Linting sets the guidelines and finds errors, bugs and issues. The configuration is set in
eslint.config.mjs.
| Command | Action |
|---|---|
npm run lint |
Run linter |
npm run lint:fix |
Run linter and fix issues |