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:deno | 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.