create-outsystems-astro 0.3.0 → 0.4.0

package/README.md

@@ -12,6 +12,7 @@ Generates [Astro Islands](https://docs.astro.build/en/concepts/islands/) for use
 - 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](https://analogjs.org/docs/packages/astro-angular/overview)
 - [React](https://docs.astro.build/en/guides/integrations-guide/react/)
 - [Vue](https://docs.astro.build/en/guides/integrations-guide/vue/)
 
@@ -46,6 +47,8 @@ dx create-outsystems-astro
 
 This will create the generated files as well as an example component.
 
+[View the full documentation](https://hs2323.github.io/create-outsystems-astro/guides/getting-started/).
+
 ## 🚀 Project Structure
 
 ```text
@@ -122,7 +125,7 @@ All commands are run from the root of the project, from a terminal:
 | `bun install`             | Installs dependencies                            |
 | `bun run dev`             | Starts local dev server at `localhost:4321`      |
 | `bun run build`           | Build distribution to `./dist/`                  |
-| `bun run output`          | Build OutSystems production site to `./output/`  |
+| `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                     |
@@ -131,10 +134,10 @@ All commands are run from the root of the project, from a terminal:
 
 | Command                   | Action                                            |
 | :------------------------ | :-----------------------------------------------  |
-| `deno install`             | Installs dependencies                            |
+| `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`          | Build OutSystems production site to `./output/`  |
+| `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                     |
@@ -163,12 +166,12 @@ pnpm run output
 
 ### Bun
 ```bash
-bun run output
+bun run output:bun
 ```
 
 ### Deno
 ```bash
-deno run output
+deno run output:deno
 ```
 
 This will create a set of files that will then need to be coverted to OutSystems components.

package/bin/cli.js

@@ -1,14 +1,21 @@
 #!/usr/bin/env node
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import prompts from "prompts";
-import { execSync } from "child_process";
+import yargs from "yargs";
+import { hideBin } from 'yargs/helpers';
+import { execSync } from "node:child_process";
+
+prompts.override(
+  yargs(hideBin(process.argv)).parse()
+);
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 const FRAMEWORKS = [
+  { title: "Angular", value: "angular" },
   { title: "React", value: "react" },
   { title: "Vue", value: "vue" }
 ];
@@ -18,7 +25,7 @@ const LOCKFILES = {
   yarn: ["yarn.lock"],
   pnpm: ["pnpm-lock.yaml"],
   bun: ["bun.lock"],
-  deno: ["deno.lock"]
+  deno: ["deno.lock", "deno.json"]
 };
 
 async function main() {
@@ -104,7 +111,9 @@ function deleteUnselectedFrameworkFolders(projectDir, selectedFrameworks) {
   for (const framework of frameworksToDelete) {
     const pageDir = path.join(projectDir, "src", "pages", framework);
     const componentDir = path.join(projectDir, "src", "framework", framework);
-
+    const testDir = path.join(projectDir, "test", "integration", framework);
+    const testE2EDir = path.join(projectDir, "test", "e2e", framework);
+    
     if (fs.existsSync(pageDir)) {
       console.log(`🗑️ Removing ${path.relative(projectDir, pageDir)}`);
       fs.rmSync(pageDir, { recursive: true, force: true });
@@ -114,6 +123,17 @@ function deleteUnselectedFrameworkFolders(projectDir, selectedFrameworks) {
       console.log(`🗑️ Removing ${path.relative(projectDir, componentDir)}`);
       fs.rmSync(componentDir, { recursive: true, force: true });
     }
+      
+    if (fs.existsSync(testDir)) {
+      console.log(`🗑️ Removing ${path.relative(projectDir, testDir)}`);
+      fs.rmSync(testDir, { recursive: true, force: true });
+    }
+
+    if (fs.existsSync(testE2EDir)) {
+      console.log(`🗑️ Removing ${path.relative(projectDir, testE2EDir)}`);
+      fs.rmSync(testE2EDir, { recursive: true, force: true });
+    }
+
   }
 }
 
@@ -128,6 +148,10 @@ function updateAstroConfig(projectDir, selectedFrameworks) {
   let content = fs.readFileSync(configPath, "utf-8");
 
   const allFrameworks = {
+    angular: {
+      import: /import\s+angular\s+from\s+['"]@analogjs\/astro-angular['"];\s*\n?/,
+      integration: /angular\s*\(\s*\{[\s\S]*?\}\s*\)\s*,?\s*/
+    },
     react: {
       import: /import\s+react\s+from\s+['"]@astrojs\/react['"];\s*\n?/,
       integration: /react\(\)\s*,?\s*/
@@ -202,7 +226,7 @@ function packageInstall(targetDir) {
         yarn: "yarn",
         pnpm: "pnpm install",
         bun: "bun install",
-        deno: "deno install",
+        deno: "deno install && deno run postinsall",
         unknown: "npm install"
       }[packageManager];
 

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "create-outsystems-astro",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Create an OutSystems Astro Island project to import as a component into your OutSystems application",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hs2323/create-outsystems-astro.git"
+  },
   "bin": {
     "create-outsystems-astro": "bin/cli.js"
   },
@@ -23,6 +27,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "yargs": "^18.0.0"
   }
 }

package/template/.github/workflows/test.yml

@@ -0,0 +1,113 @@
+name: Test
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+env:
+  NODE_VERSION: '24.13.0'
+
+jobs:
+
+  format:
+    runs-on: ubuntu-latest
+
+    steps:  
+      - name: Checkout code
+        uses: actions/checkout@v6.0.1
+
+      - name: Use Node.js
+        uses: actions/setup-node@v6.2.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Run format
+        run: npm run format
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:  
+      - name: Checkout code
+        uses: actions/checkout@v6.0.1
+
+      - name: Use Node.js
+        uses: actions/setup-node@v6.2.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Run lint
+        run: npm run lint
+
+  security:
+    runs-on: ubuntu-latest
+
+    steps:  
+      - name: Checkout code
+        uses: actions/checkout@v6.0.1
+
+      - name: Use Node.js
+        uses: actions/setup-node@v6.2.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Run security check
+        run: npm audit
+
+  test:
+    runs-on: ubuntu-latest
+
+    steps:  
+      - name: Checkout code
+        uses: actions/checkout@v6.0.1
+
+      - name: Use Node.js
+        uses: actions/setup-node@v6.2.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm run test
+
+  teste2e:
+    runs-on: ubuntu-latest
+
+    steps:  
+      - name: Checkout code
+        uses: actions/checkout@v6.0.1
+
+      - name: Use Node.js
+        uses: actions/setup-node@v6.2.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright
+        run: npm run test:e2e:install
+
+      - name: Run tests
+        run: npm run test:e2e
+
+  typecheck:
+    runs-on: ubuntu-latest
+
+    steps:  
+      - name: Checkout code
+        uses: actions/checkout@v6.0.1
+
+      - name: Use Node.js
+        uses: actions/setup-node@v6.2.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run type check
+        run: npm run typecheck

package/template/.gitignore

@@ -25,3 +25,10 @@ pnpm-debug.log*
 
 # output folder
 output/
+
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+/playwright/.auth/

package/template/.prettierignore

@@ -0,0 +1,11 @@
+.github/
+bun.lock
+deno.lock
+dist/
+node_modules/
+output/
+package-lock.json
+package.json
+patches/
+pnpm-lock.yaml
+yarn.lock

package/template/AGENTS.md

@@ -1,14 +1,17 @@
 # OutSystems Astro Islands Development Instructions
 
 ## Project Context
+
 - This is not an Astro project that will be deployed on its own. It is only used for the output generation.
 - The output generation will be only client side. No server side rendering or server side components will be used.
 - The Astro Islands can be used generated with the following frameworks:
-    - React
-    - Vue
+  - Angular - Documentation available at https://analogjs.org/docs/packages/astro-angular/overview
+  - React - Documentation available at https://docs.astro.build/en/guides/integrations-guide/react/
+  - Vue - https://docs.astro.build/en/guides/integrations-guide/vue/
 - Prefer to use TypeScript when possible.
 
 ## OutSystems
+
 - This project works for OutSystems 11 (O11) Reactive and OutSystems Developer Cloud (ODC). It does not work with OutSystems 11 Traditional projects.
 - The documentation for importing a component into OutSystems 11 is availabe at https://hs2323.github.io/create-outsystems-astro/guides/outsystems/o11/.
 - The documentation for importing a component into OutSystems 11 is availabe at https://hs2323.github.io/create-outsystems-astro/guides/outsystems/o11/.
@@ -16,32 +19,44 @@
 ## Development
 
 ### Starting project
+
+- Documentation about usage of the generator is located at: https://hs2323.github.io/create-outsystems-astro/guides/astro/.
 - The project can intialized from the Create OutSystems Astro package (https://www.npmjs.com/package/create-outsystems-astro).
-- In this document, for any reference to running package manager script, the ```PM``` attribute should be replaced with whatever package manager the user is using.
+- In this document, for any reference to running package manager script, the `PM` attribute should be replaced with whatever package manager the user is using.
 
 ### Pages
-- The files in src/pages/*.astro are used as a starting point and holds the components for generation.  They can be tested by running ```npm run dev```. That will show what the component looks like as rendered. The sample example pages are broken out by framework name (src/pages/react, src/pages/vue, etc).  This page will house the component(s) entry points. 
+
+- The files in src/pages/\*.astro are used as a starting point and holds the components for generation. They can be tested by running `npm run dev`. That will show what the component looks like as rendered. The sample example pages are broken out by framework name (src/pages/react, src/pages/vue, etc). This page will house the component(s) entry points.
 - When importing a component, the component must have the attribute of the client:only= + the framework name.
-    - React: ```client:only="react"```.
-    - Vue: ```client:only="vue"```.
+  - React: `client:only="react"`.
+  - Vue: `client:only="vue"`.
+  - Angular: `client:visible`.
 
 ### Components
-- The components live in the folder framework/[NAME]/ (src/framework/react, src/framework/vue, etc)) with each framework having its own folder. This is recommended but can be renamed to something else.
+
+- The components live in the folder framework/[NAME]/ (src/framework/angular, src/framework/react and src/framework/vue ) with each framework having its own folder. The framework folder should stay in place as the components will be rendered from there. The Angular components will only be transformed by Astro if they are in the framework/angular folder.
 
 ### Parameters
+
 - Parameters are assigned as attributes on the component. Each framework will then handle them as incoming parameters.
-- OutSystems will pass in parameters already prepared for the ````<astro-island>```. It already has copied the Astro method of serialization in https://github.com/withastro/astro/blob/main/packages/astro/src/runtime/server/serialize.ts.
+- OutSystems will pass in parameters already prepared for the ``<astro-island>`. It already has copied the Astro method of serialization in https://github.com/withastro/astro/blob/main/packages/astro/src/runtime/server/serialize.ts.
 
 #### Slots
-Astro slots can be sent in.  A slot can be either the default one or the named one.  Each framework handles slots differently. Slots can only be HTML elements and cannot be components of a framework.
+
+Astro slots can be sent in. A slot can be either the default one or the named one. Each framework handles slots differently. Slots can only be HTML elements and cannot be components of a framework.
 
 ##### React
-- In React, slots are handled as props.  The default slot is the ```children``` prop. A named slot will have the name of its slot as the parameter. For example, a slot with the following:
+
+- In React, slots are handled as props. The default slot is the `children` prop. A named slot will have the name of its slot as the parameter. For example, a slot with the following:
+
 ```js
-<div slot="header">
+<div slot="header">Header content</div>
 ```
-will have the parameter named header. 
-- The slots are then rendered using the regular React rendering parameter method.  With the following Astro component:
+
+will have the parameter named header.
+
+- The slots are then rendered using the regular React rendering parameter method. With the following Astro component:
+
 ```js
 ---
 import CounterComponent from '../../framework/react/Counter';
@@ -55,7 +70,9 @@ import CounterComponent from '../../framework/react/Counter';
     </div>
 </CounterComponent>
 ```
-the slots will render as:
+
+the slots can be used as:
+
 ```js
 export default function Counter({
 	children,
@@ -67,41 +84,78 @@ export default function Counter({
 
 	return (
 		<>
-            {header}
+      {header}
 			<div>
 				{children}
 			</div>
 		</>
 	);
 }
-
 ```
 
 ##### Vue
-- In Vue, slots are handled as by using the <slot /> tag.  The default slot is the is just <slot />. A named slot will have the name of its slot as an attribute such as <slot name="header" />. Placement of the slot will determine where the slot will render.
+
+- In Vue, slots are handled as by using the <slot /> tag. The default slot is the is just <slot />. A named slot will have the name of its slot as an attribute such as <slot name="header" />. Placement of the slot will determine where the slot will render.
+
+```js
+---
+import CounterComponent from '../../framework/react/Counter';
+---
+<CounterComponent client:only="vue">
+    <div slot="header">
+        Counter
+    </div>
+    <div style="text-align: center;">
+        <p>Slot content!</p>
+    </div>
+</CounterComponent>
+```
+
+the slots can be used as:
+
+```js
+<template>
+  <div>
+    <slot name="header" />
+    <slot />
+  </div>
+</template>
+```
+
+##### Angular
+
+Angular does not support the use of slots. Any use of slots with Angular should be discouraged.
 
 ### Testing
-- No testing is built into this generator.  It is recommended to use best practices for each framework. For example, in React, use Vitest for unit testing, React Testing Library for integration testing of components and PlayWright for end-to-end testing.
+
+- There is a preset set of testing tools, but can be changed after generation.
+- The unit testing library setup is Vitest. The unit tests are located in `test/unit` folder.
+- The integration testing library is Testing Library with an equivalent library per framework. Each framework is in its own folder in `test/integration/[FRAMEWORK]`.
+- The end-to-end testing library is Playwright. Each framework is in its own folder in `test/e2e/[FRAMEWORK]`.
 
 ### Linting and formatting
-- No linting or formatting is built into this generator. It is recommended to add Prettier for formatting and ESLint for linting.
+
+- Prettier is currently added for formatting. ESLint is used for linting.
 
 ### TypeScript
+
 - If using TypeScript, it is recommended to do a TypeScript check.
 
 ### Handlers
-- Incoming functions from OutSystems cannot be passed as function handlers. The way that OutSystems will invoke them  is by binding the function with the name to the ```document``` object of the page.  Then it will pass in that name as a parameter.  For example, if you need a function handler of ```ShowMessage```, it will need to be called as ```document[ShowMessage]```.
+
+- Incoming functions from OutSystems cannot be passed as function handlers. The way that OutSystems will invoke them is by binding the function with the name to the `document` object of the page. Then it will pass in that name as a parameter. For example, if you need a function handler of `ShowMessage`, it will need to be called as `document[ShowMessage]`.
 - Passing in basic text, number and boolean should be fine to the handler. Any array or object must be JSON stringified prior to being passed into the handler.
 
 ## Generating output
-- The ```.env.template``` must be copied over to ```.env```.
-- The name of the module/library/application where the component will live must be set in the ```ASSET_URL``` variable of the ```.env``` file.
-- Run the command ```PM run output```. This will run the Astro build and then run an additional step to generate the output necessary for importing into OutSystems.
+
+- The `.env.template` must be copied over to `.env`.
+- The name of the module/library/application where the component will live must be set in the `ASSET_URL` variable of the `.env` file.
+- Run the command `PM run output`. This will run the Astro build and then run an additional step to generate the output necessary for importing into OutSystems.
 - The output will be in the output/ folder. The contents are:
-    - HTML file(s) *.html:
-        - This will contain only the ```<astro-island>``` component. It will be necessary for the users to copy over the ```component-url```, ```renderer-url``` and ```opts```. The rest will either be custom built in OutSystems or not needed. The ```uid``` will be generated by OutSystems. The ```component-export```, ```client```, ```ssr``` and ```await-children``` will be automatically added in the OutSystems Islands module.  
-        - The slot content will be converted and parsed in a way that can be then dropped in as text directly into the OutSystem parameter.
-    - JavaScript files *.js:
-        - The JavaScript files will be imported as resources and then mapped as parameters when importing the Islands module.
-    - Asset files:
-        The ```/assets``` folder may contain images, stylesheets and other assets.  For images, they should be copied in as resources into the module/library/component/application.  Any CSS must be manually copied from the ```.css``` files and manually imported into the project or the block level CSS.
+  - HTML file(s) \*.html:
+    - This will contain only the `<astro-island>` component. It will be necessary for the users to copy over the `component-url`, `renderer-url` and `opts`. The rest will either be custom built in OutSystems or not needed. The `uid` will be generated by OutSystems. The `component-export`, `client`, `ssr` and `await-children` will be automatically added in the OutSystems Islands module.
+    - The slot content will be converted and parsed in a way that can be then dropped in as text directly into the OutSystem parameter.
+  - JavaScript files \*.js:
+    - The JavaScript files will be imported as resources and then mapped as parameters when importing the Islands module.
+  - Asset files:
+    The `/assets` folder may contain images, stylesheets and other assets. For images, they should be copied in as resources into the module/library/component/application. Any CSS must be manually copied from the `.css` files and manually imported into the project or the block level CSS.

package/template/CLAUDE.md

@@ -2,6 +2,6 @@
 
 ## Relationship to AGENTS.md
 
-This document extends and specializes the general agent behaviors defined in [AGENTS.md](./AGENTS.md). 
+This document extends and specializes the general agent behaviors defined in [AGENTS.md](./AGENTS.md).
 
 **Precedence Rule**: When there are conflicts or overlapping guidance between these documents, **CLAUDE.md takes precedence** for all interactions with Claude models. AGENTS.md provides the foundational agent patterns, while this document contains Claude-specific overrides and optimizations.

package/template/GEMINI.md

@@ -2,11 +2,12 @@
 
 ## Relationship to AGENTS.md
 
-This document extends and specializes the general agent behaviors defined in [AGENTS.md](./AGENTS.md). 
+This document extends and specializes the general agent behaviors defined in [AGENTS.md](./AGENTS.md).
 
 **Precedence Rule**: When there are conflicts or overlapping guidance between these documents, **GEMINI.md takes precedence** for all interactions with Gemini models. AGENTS.md provides the foundational agent patterns, while this document contains Gemini-specific overrides and optimizations.
 
 ---
 
 ## Imported Context
+
 @./AGENTS.md

package/template/astro.config.mjs

@@ -1,29 +1,53 @@
 // @ts-check
-import react from '@astrojs/react';
-import vue from '@astrojs/vue';
-import { defineConfig } from 'astro/config';
+import angular from "@analogjs/astro-angular";
+import react from "@astrojs/react";
+import vue from "@astrojs/vue";
+import { defineConfig } from "astro/config";
 
 // https://astro.build/config
 export default defineConfig({
-  integrations: [react(), vue()],
   build: {
-        inlineStylesheets: 'always'
+    inlineStylesheets: "always",
+  },
+  integrations: [
+    angular({
+      vite: {
+        transformFilter: (_code, id) => {
+          return id.includes("src/framework/angular");
+        },
+      },
+    }),
+    react(),
+    vue(),
+  ],
+  server: {
+    host: true,
+    port: 4321,
   },
   vite: {
     build: {
       rollupOptions: {
         output: {
+          assetFileNames: `assets/[name]_[hash].[ext]`,
+          chunkFileNames: `[name]_[hash].js`,
+          entryFileNames: `[name]_[hash].js`,
           manualChunks: (id) => {
-            if (id.includes('node_modules') || id.includes('src')) {
-              return 'app.js';
+            if (id.includes("node_modules")) {
+              return "app.js";
             }
-            return 'app.js';
           },
-          entryFileNames: `[name]_[hash].js`,
-          chunkFileNames: `[name]_[hash].js`,
-          assetFileNames: `assets/[name]_[hash].[ext]`,
         },
       },
     },
+    resolve: {
+      alias: {
+        fs: "node:fs",
+        http: "node:http",
+        https: "node:https",
+        os: "node:os",
+        path: "node:path",
+        url: "node:url",
+      },
+    },
   },
-});
+});