create-outsystems-astro 0.1.0 → 0.3.0

package/README.md

@@ -2,9 +2,9 @@
 Generates [Astro Islands](https://docs.astro.build/en/concepts/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 not be difficult/not possible to build directly in OutSystems.
+- 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 traditional code.
+- 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](https://success.outsystems.com/documentation/11/integration_with_external_systems/extend_logic_with_your_own_code/) and [ODC](https://success.outsystems.com/documentation/outsystems_developer_cloud/building_apps/extend_your_apps_with_custom_code/).
@@ -12,13 +12,38 @@ 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
-- [React](https://docs.astro.build/en/guides/integrations-guide/react/).
+- [React](https://docs.astro.build/en/guides/integrations-guide/react/)
+- [Vue](https://docs.astro.build/en/guides/integrations-guide/vue/)
 
 ## Getting started
 Run the Create OutSystems Astro generator:
+
+### npm
 ```bash
 npx create-outsystems-astro
 ```
+
+### Yarn
+```bash
+yarn create outsystems-astro
+```
+
+### pnpm
+```bash
+pnpm dlx create-outsystems-astro
+```
+
+### Bun
+```bash
+bunx create-outsystems-astro
+```
+
+### Deno
+The Deno DX command is available in [Deno 2.6](https://deno.com/blog/v2.6).
+```bash
+dx create-outsystems-astro
+```
+
 This will create the generated files as well as an example component.
 
 ## 🚀 Project Structure
@@ -54,6 +79,8 @@ Stylesheets that may apply to the component.
 
 All commands are run from the root of the project, from a terminal:
 
+### npm
+
 | Command                   | Action                                           |
 | :------------------------ | :----------------------------------------------- |
 | `npm install`             | Installs dependencies                            |
@@ -64,12 +91,84 @@ All commands are run from the root of the project, from a terminal:
 | `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
 | `npm run astro -- --help` | Get help using the Astro CLI                     |
 
+### 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                     |
+
+### 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                     |
+
+### 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`          | 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                     |
+
+### Deno
+
+| Command                   | Action                                            |
+| :------------------------ | :-----------------------------------------------  |
+| `deno install`             | 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 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                     |
+
+## Getting Started
+Delete the demo application under the ```src``` folder and being to build your own application. 
 
 ## Converting to OutSystems
 
-Once development is complete, run:
+Once development is complete, run the output generation command:
+
+### npm
 ```bash
 npm run output
 ```
 
+### Yarn
+```bash
+yarn run output
+```
+
+### pnpm
+```bash
+pnpm run output
+```
+
+### Bun
+```bash
+bun run output
+```
+
+### Deno
+```bash
+deno run output
+```
+
 This will create a set of files that will then need to be coverted to OutSystems components.

package/bin/cli.js

@@ -8,6 +8,19 @@ import { execSync } from "child_process";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+const FRAMEWORKS = [
+  { title: "React", value: "react" },
+  { title: "Vue", value: "vue" }
+];
+
+const LOCKFILES = {
+  npm: ["package-lock.json"],
+  yarn: ["yarn.lock"],
+  pnpm: ["pnpm-lock.yaml"],
+  bun: ["bun.lock"],
+  deno: ["deno.lock"]
+};
+
 async function main() {
   console.log("🚀 Welcome to create-outsystems-astro!");
 
@@ -26,6 +39,28 @@ async function main() {
   console.log("📦 Copying template...");
   copyDir(templateDir, targetDir);
 
+  const packageManager = packageInstall(targetDir);
+
+  let selectedFrameworks = [];
+
+  while (selectedFrameworks.length === 0) {
+    const frameworkResponse = await prompts({
+      type: "multiselect",
+      name: "frameworks",
+      message: "Which frameworks do you want to include?",
+      choices: FRAMEWORKS,
+      hint: "- Space to select. Enter to confirm",
+      validate: value =>
+        value.length > 0 ? true : "Please select at least one framework."
+    });
+
+    selectedFrameworks = frameworkResponse.frameworks || [];
+  }
+
+  deleteUnselectedFrameworkFolders(targetDir, selectedFrameworks);
+
+  updateAstroConfig(targetDir, selectedFrameworks);
+
   const readmeSrc = path.resolve(__dirname, "../README.md");
   const readmeDest = path.join(targetDir, "README.md");
 
@@ -33,20 +68,14 @@ async function main() {
     fs.copyFileSync(readmeSrc, readmeDest);
   }
 
-  // Install dependencies
-  console.log("📦 Installing dependencies...");
-  try {
-    execSync("npm install", { cwd: targetDir, stdio: "inherit" });
-  } catch {
-    console.warn("⚠️ Failed to automatically install dependencies.");
-  }
+
 
   console.log(`
 ✅ All done!
 
 Next steps:
   cd ${response.projectName}
-  npm run dev
+  ${packageManager} run dev
 `);
 }
 
@@ -65,6 +94,130 @@ function copyDir(src, dest) {
   }
 }
 
+function deleteUnselectedFrameworkFolders(projectDir, selectedFrameworks) {
+  const allFrameworks = FRAMEWORKS.map(f => f.value);
+
+  const frameworksToDelete = allFrameworks.filter(
+    f => !selectedFrameworks.includes(f)
+  );
+
+  for (const framework of frameworksToDelete) {
+    const pageDir = path.join(projectDir, "src", "pages", framework);
+    const componentDir = path.join(projectDir, "src", "framework", framework);
+
+    if (fs.existsSync(pageDir)) {
+      console.log(`🗑️ Removing ${path.relative(projectDir, pageDir)}`);
+      fs.rmSync(pageDir, { recursive: true, force: true });
+    }
+
+    if (fs.existsSync(componentDir)) {
+      console.log(`🗑️ Removing ${path.relative(projectDir, componentDir)}`);
+      fs.rmSync(componentDir, { recursive: true, force: true });
+    }
+  }
+}
+
+function updateAstroConfig(projectDir, selectedFrameworks) {
+  const configPath = path.join(projectDir, "astro.config.mjs");
+
+  if (!fs.existsSync(configPath)) {
+    console.warn("⚠️ astro.config.mjs not found, skipping integration cleanup.");
+    return;
+  }
+
+  let content = fs.readFileSync(configPath, "utf-8");
+
+  const allFrameworks = {
+    react: {
+      import: /import\s+react\s+from\s+['"]@astrojs\/react['"];\s*\n?/,
+      integration: /react\(\)\s*,?\s*/
+    },
+    vue: {
+      import: /import\s+vue\s+from\s+['"]@astrojs\/vue['"];\s*\n?/,
+      integration: /vue\(\)\s*,?\s*/
+    }
+  };
+
+  for (const [framework, patterns] of Object.entries(allFrameworks)) {
+    if (!selectedFrameworks.includes(framework)) {
+      content = content.replace(patterns.import, "");
+      content = content.replace(patterns.integration, "");
+    }
+  }
+
+  // Clean up trailing commas inside integrations array
+  content = content.replace(
+    /integrations:\s*\[\s*,/g,
+    "integrations: ["
+  );
+  content = content.replace(
+    /,\s*\]/g,
+    "]"
+  );
+
+  fs.writeFileSync(configPath, content, "utf-8");
+  console.log("🛠️ Updated astro.config.mjs integrations");
+}
+
+function detectPackageManager() {
+  if (typeof Deno !== "undefined") return "deno";
+
+  const ua = process.env.npm_config_user_agent || "";
+
+  if (ua.startsWith("npm/")) return "npm";
+  if (ua.startsWith("yarn/")) return "yarn";
+  if (ua.startsWith("pnpm/")) return "pnpm";
+  if (ua.startsWith("bun/")) return "bun";
+
+  return "unknown";
+}
+
+function cleanupLockfiles(projectDir, activePackageManager) {
+  for (const [packageManager, files] of Object.entries(LOCKFILES)) {
+    if (packageManager === activePackageManager) continue;
+
+    for (const file of files) {
+      const filePath = path.join(projectDir, file);
+      if (fs.existsSync(filePath)) {
+        fs.rmSync(filePath, { force: true });
+        console.log(`🗑️ Removed ${file}`);
+      }
+    }
+  }
+}
+
+function packageInstall(targetDir) {
+   try {
+      const packageManager = detectPackageManager();
+      console.log(`🧰 Detected package manager: ${packageManager}`);
+      
+      if (packageManager === "unknown") {
+        console.warn("⚠️ Could not detect package manager — keeping all lockfiles.");
+      } else {
+        cleanupLockfiles(targetDir, packageManager);
+      }
+
+      const installCmd = {
+        npm: "npm install",
+        yarn: "yarn",
+        pnpm: "pnpm install",
+        bun: "bun install",
+        deno: "deno install",
+        unknown: "npm install"
+      }[packageManager];
+
+      console.log(`📦 Installing dependencies using ${packageManager}...`);
+      execSync(installCmd, {
+        cwd: targetDir,
+        stdio: "inherit"
+      });
+
+      return packageManager
+   } catch {
+      console.warn("⚠️ Failed to automatically install dependencies.");
+    }
+}
+
 main().catch(err => {
   console.error(err);
   process.exit(1);

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "create-outsystems-astro",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Create an OutSystems Astro Island project to import as a component into your OutSystems application",
   "bin": {
     "create-outsystems-astro": "bin/cli.js"
   },
   "files": [
     "bin",
-    "template"
+    "template",
+    "template/.gitignore"
   ],
   "publishConfig": {
     "access": "public"

package/template/.github/copilot-instructions.md

@@ -0,0 +1,6 @@
+# Copilot instructions
+
+This file is the authoritative Copilot instruction file for this repository.
+If any content in AGENTS.md conflicts with the instructions below, always follow the instructions in this file.
+
+Reference (for additional details): [AGENTS.md](../AGENTS.md)

package/template/.gitignore

@@ -0,0 +1,27 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/
+
+# output folder
+output/

package/template/AGENTS.md

@@ -0,0 +1,107 @@
+# 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
+- 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/.
+
+## Development
+
+### Starting project
+- 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.
+
+### 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. 
+- 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"```.
+
+### 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.
+
+### 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.
+
+#### 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.
+
+##### 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:
+```js
+<div slot="header">
+```
+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';
+---
+<CounterComponent client:only="react">
+    <div slot="header">
+        Counter
+    </div>
+    <div style="text-align: center;">
+        <p>Slot content!</p>
+    </div>
+</CounterComponent>
+```
+the slots will render as:
+```js
+export default function Counter({
+	children,
+	header,
+}: {
+	children: React.ReactNode;
+	header: React.ReactNode;
+}) {
+
+	return (
+		<>
+            {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.
+
+### 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.
+
+### Linting and formatting
+- No linting or formatting is built into this generator. It is recommended to add Prettier for formatting and ESLint 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]```.
+- 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 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.

package/template/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+## Relationship to 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

@@ -0,0 +1,12 @@
+# GEMINI.md
+
+## Relationship to 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,11 +1,11 @@
 // @ts-check
 import react from '@astrojs/react';
+import vue from '@astrojs/vue';
 import { defineConfig } from 'astro/config';
 
-
 // https://astro.build/config
 export default defineConfig({
-  integrations: [react()],
+  integrations: [react(), vue()],
   build: {
         inlineStylesheets: 'always'
   },
@@ -26,4 +26,4 @@ export default defineConfig({
       },
     },
   },
-});
+});