Skip to content

Astro setup

Run the Create OutSystems Astro generator:

Terminal window
npx create-outsystems-astro

Select 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.

/
β”œβ”€β”€ 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.json

It 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.

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.

The location of the component code.

For JSX based frameworks, you must use the jsxImportSource header at the top of the page:

/** @jsxImportSource preact */
/** @jsxImportSource @qwik.dev/core */
/** @jsxImportSource react */
/** @jsxImportSource solid-js */
/** @jsxImportSource @stencil/core */

Any image assets.

Stylesheets that may apply to the component.

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

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 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>

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.

  • Copy the environment template file to .env.

    Terminal window
    cp .env.template .env
  • Update the .env file and modify the ASSET_PATH value 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).

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.

  • Vitest The unit tests are placed in the test/unit folder. This is primarily for testing functions and logic.

The integration tests are placed in the test/integration folder. This tests the interaction between the components as a whole.

  • Playwright The end-to-end tests are placed in the test/e2e folder. 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 .prettierrc file.
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