OutSystems Astro Islands

Generates Astro Islands for use in OutSystems that can create self contained interactive code elements from different frameworks. It allows an extension of the front-end with these dynamic libraries.

When to use this library

• Custom interactive elements that would be difficult/not possible to build directly in OutSystems.
• Wrappers around interactive elements built in other front-end frameworks.
• Direct migration of external traditional code.

When NOT to use this library

• You will most likely not need to use this library for most of the front-end development. This is similar in use to the custom code development in for the back-end in O11 and ODC.
• If the functionality is easily buidable in Service Studio.
• Loading performance of component must be instant. The Astro Island will load after the page/screen has loaded since the initializer and tag will be loaded after.

Current supported frameworks

• Angular
• Preact
• React
• SolidJS
• Svelte
• Vue

Getting started

Run the Create OutSystems Astro generator:

npm

npx create-outsystems-astro

Yarn

yarn create outsystems-astro

pnpm

pnpm dlx create-outsystems-astro

Bun

bunx create-outsystems-astro

Deno

The Deno DX command is available in Deno 2.6.

dx create-outsystems-astro

This will create the generated files as well as an example component.

View the full documentation.

🚀 Project Structure

/
├── public/
├── src/
│   └── framework/
│       └── [NAME]/
│           └── components/
│               └── Counter.tsx
│   └── lib/
│       └── library.ts
│   └── images/
│       └── image.png
│   └── pages/
│       └── [NAME]/
│           └── page.astro
│   └── styles/
│       └── index.css
│   └── stores/
│       └── store.ts
├── test/
│   └── e2e
│       └── [NAME]/
│           └── counter.spec.ts
│   └── integration
│       └── [NAME]/
│           └── counter.test.tsx
│           └── conter.test.ts
│   └── unit
        └── counter.test.ts
└── package.json

Src

Framework Components

The location of the component code. Each framework has its own separate folder.

Lib

Cane be use for shared/library logic that is not part of the visual presentation of the component.

Images

Any image assets.

Pages

Each page inside of the pages file should represent an Island that will be imported into OutSystems. This is for setup/development and the actual page will not be used for the final output. Pages may be split by framework if using multiple frameworks.

Styles

Stylesheets that may apply to the component.

Stores

Nano Stores for use in components.

Test

E2E

End-to-end tests using Playwright.

Integration

Integration tests that test the whole component structure. Written using Testing Library specific providers.

Unit

Unit tests for functions or shared code/libraries.

🧞 Commands

All commands are run from the root of the project, from a terminal:

npm

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
npm run audit:npm	Run audit of modules

Yarn

Command	Action
yarn install	Installs dependencies
yarn run dev	Starts local dev server at localhost:4321
yarn run build	Build distribution to ./dist/
yarn run output	Build OutSystems production site to ./output/
yarn run preview	Preview build locally, before creating output
yarn run astro ...	Run CLI commands like astro add, astro check
yarn run astro -- --help	Get help using the Astro CLI
yarn run audit:yarn	Run audit of modules

pnpm

Command	Action
pnpm install	Installs dependencies
pnpm run dev	Starts local dev server at localhost:4321
pnpm run build	Build distribution to ./dist/
pnpm run output	Build OutSystems production site to ./output/
pnpm run preview	Preview build locally, before creating output
pnpm run astro ...	Run CLI commands like astro add, astro check
pnpm run astro -- --help	Get help using the Astro CLI
pnpm run audit:pnpm	Run audit of modules

Bun

Command	Action
bun install	Installs dependencies
bun run dev	Starts local dev server at localhost:4321
bun run build	Build distribution to ./dist/
bun run output:bun	Build OutSystems production site to ./output/
bun run preview	Preview build locally, before creating output
bun run astro ...	Run CLI commands like astro add, astro check
bun run astro -- --help	Get help using the Astro CLI
bun run audit:bun	Run audit of modules

Deno

Command	Action
deno install && deno run postinstall	Installs dependencies
deno run dev	Starts local dev server at localhost:4321
deno run build	Build distribution to ./dist/
deno run output:deno	Build OutSystems production site to ./output/
deno run preview	Preview build locally, before creating output
deno run astro ...	Run CLI commands like astro add, astro check
deno run astro -- --help	Get help using the Astro CLI
deno run audit:deno	Run audit of modules

Getting Started

Delete the demo application under the src folder and being to build your own application. It is recommended to keep the folder structure. The frameworks/[NAME]/components should be kept for asset building.

Converting to OutSystems

Once development is complete, run the output generation command:

npm

npm run output

Yarn

yarn run output

pnpm

pnpm run output

Bun

bun run output:bun

Deno

deno run output:deno

This will create a set of files that will then need to be coverted to OutSystems components.