create-outsystems-astro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hs2323
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# OutSystems Astro Islands
+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.
+- Wrappers around interactive elements built in other front-end frameworks.
+- Direct migration of 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/).
+- 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
+- [React](https://docs.astro.build/en/guides/integrations-guide/react/).
+
+## Getting started
+Run the Create OutSystems Astro generator:
+```bash
+npx create-outsystems-astro
+```
+This will create the generated files as well as an example component.
+
+## 🚀 Project Structure
+
+```text
+/
+├── public/
+├── src/
+│   └── components/
+│       └── Counter.tsx
+│   └── images/
+│       └── image.png
+│   └── pages/
+│       └── counter.astro
+│   └── styles/
+│       └── index.css
+└── package.json
+```
+
+### Pages
+Each page inside of the pages file should represent an Island that will be imported into OutSystems.
+
+### Components
+The location of the component code.
+
+### Images
+Any image assets.
+
+### Styles
+Stylesheets that may apply to the component.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| 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                     |
+
+
+## Converting to OutSystems
+
+Once development is complete, run:
+```bash
+npm run output
+```
+
+This will create a set of files that will then need to be coverted to OutSystems components.

package/bin/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import prompts from "prompts";
+import { execSync } from "child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function main() {
+  console.log("🚀 Welcome to create-outsystems-astro!");
+
+  // Ask for project name
+  const response = await prompts({
+    type: "text",
+    name: "projectName",
+    message: "What should we name your project?",
+    initial: "outsystems-astro-app"
+  });
+
+  const targetDir = path.resolve(process.cwd(), response.projectName);
+  const templateDir = path.join(__dirname, "..", "template");
+
+  // Copy files
+  console.log("📦 Copying template...");
+  copyDir(templateDir, targetDir);
+
+  const readmeSrc = path.resolve(__dirname, "../README.md");
+  const readmeDest = path.join(targetDir, "README.md");
+
+  if (fs.existsSync(readmeSrc)) {
+    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
+`);
+}
+
+// Simple recursive copy
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "create-outsystems-astro",
+  "type": "module",
+  "version": "0.1.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"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "astro",
+    "outsystems",
+    "starter",
+    "create",
+    "template"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "prompts": "^2.4.2"
+  }
+}

package/template/.env.template

@@ -0,0 +1,2 @@
+# Path in OutSystems to image locations.
+ASSET_PATH=

package/template/astro.config.mjs

@@ -0,0 +1,29 @@
+// @ts-check
+import react from '@astrojs/react';
+import { defineConfig } from 'astro/config';
+
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [react()],
+  build: {
+        inlineStylesheets: 'always'
+  },
+  vite: {
+    build: {
+      rollupOptions: {
+        output: {
+          manualChunks: (id) => {
+            if (id.includes('node_modules') || id.includes('src')) {
+              return 'app.js';
+            }
+            return 'app.js';
+          },
+          entryFileNames: `[name]_[hash].js`,
+          chunkFileNames: `[name]_[hash].js`,
+          assetFileNames: `assets/[name]_[hash].[ext]`,
+        },
+      },
+    },
+  },
+});

package/template/output.ts

@@ -0,0 +1,244 @@
+import * as fs from "fs";
+import * as path from "path";
+import beautify from "js-beautify";
+import dotenv from 'dotenv';
+dotenv.config();
+
+const { html: beautifyHtml } = beautify;
+
+/**
+ * Extracts all <astro-island>...</astro-island> blocks from HTML.
+ */
+function keepAstroIslands(html: string): string {
+  const astroIslandRegex = /<astro-island\b[^>]*>[\s\S]*?<\/astro-island>/gi;
+  const islands = html.match(astroIslandRegex) || [];
+  return islands.join("\n");
+}
+
+function formatAstroIslandAttributes(html: string): string {
+  // For each <astro-island ...>, put attributes on new lines
+  return html.replace(
+    /<astro-island\b([^>]*)>/gi,
+    (match, attrs) => {
+
+      // 🔥 Convert HTML-encoded quotes to actual quotes
+      const decoded = attrs.replace(/&quot;/g, '""');
+
+      // Split attributes by whitespace
+      const formattedAttrs = decoded
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map(attr => `  ${attr}`) // indent each attr
+        .join("\n");
+
+      return `<astro-island\n${formattedAttrs}>`;
+    }
+  );
+}
+
+/**
+ * Recursively collects files with a given extension in a directory.
+ */
+function getAllFilesWithExtension(dir: string, ext: string): string[] {
+  let results: string[] = [];
+
+  for (const file of fs.readdirSync(dir)) {
+    const filePath = path.join(dir, file);
+    const stat = fs.statSync(filePath);
+
+    if (stat.isDirectory()) {
+      results = results.concat(getAllFilesWithExtension(filePath, ext));
+    } else if (filePath.endsWith(ext)) {
+      results.push(filePath);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Ensures a directory exists before writing or copying.
+ */
+function ensureDirExists(dir: string) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Recursively deletes a directory.
+ */
+function clearDirectory(dir: string) {
+  if (!fs.existsSync(dir)) return;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      clearDirectory(entryPath);
+      fs.rmdirSync(entryPath);
+    } else {
+      fs.unlinkSync(entryPath);
+    }
+  }
+}
+
+/**
+ * Recursively copies a directory and its contents.
+ */
+function copyDirectory(src: string, dest: string) {
+  if (!fs.existsSync(src)) {
+    console.warn(`⚠️ Source directory not found: ${src}`);
+    return;
+  }
+
+  ensureDirExists(dest);
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirectory(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Converts dist/foo/index.html → output/foo.html
+ * Keeps dist/index.html as output/index.html
+ */
+function getFlattenedHtmlOutputPath(inputFile: string, inputDir: string, outputDir: string): string {
+  const relative = path.relative(inputDir, inputFile);
+  const parts = relative.split(path.sep);
+
+  if (parts.length > 1 && parts[parts.length - 1] === "index.html") {
+    const folderName = parts[parts.length - 2];
+    return path.join(outputDir, `${folderName}.html`);
+  }
+
+  return path.join(outputDir, relative);
+}
+
+/**
+ * Processes and flattens HTML files (expanded output)
+ */
+function processAllHTML(inputDir: string, outputDir: string): void {
+  const htmlFiles = getAllFilesWithExtension(inputDir, ".html");
+  if (htmlFiles.length === 0) {
+    console.warn(`⚠️ No HTML files found in ${inputDir}`);
+    return;
+  }
+
+  for (const inputFile of htmlFiles) {
+    const outputFile = getFlattenedHtmlOutputPath(inputFile, inputDir, outputDir);
+    const html = fs.readFileSync(inputFile, "utf-8");
+
+    // Filter to only keep astro-islands
+    const filtered = keepAstroIslands(html);
+
+    // Beautify / expand the HTML before writing
+    const beautified = beautifyHtml(filtered, {
+      indent_size: 2,
+      preserve_newlines: true,
+      max_preserve_newlines: 1,
+      wrap_line_length: 120,
+      unformatted: ["code", "pre", "em", "strong"],
+    });
+
+    const prettyHtml = formatAstroIslandAttributes(beautified);
+
+    ensureDirExists(path.dirname(outputFile));
+    fs.writeFileSync(outputFile, prettyHtml, "utf-8");
+
+    console.log(`✅ Processed HTML: ${path.relative(inputDir, inputFile)} → ${path.relative(outputDir, outputFile)}`);
+  }
+}
+
+/**
+ * Copies all .js files from dist/ to output/
+ */
+function copyAllJSFiles(inputDir: string, outputDir: string): void {
+  const jsFiles = getAllFilesWithExtension(inputDir, ".js");
+  if (jsFiles.length === 0) {
+    console.warn(`⚠️ No JavaScript files found in ${inputDir}`);
+    return;
+  }
+
+  for (const inputFile of jsFiles) {
+    const relativePath = path.relative(inputDir, inputFile);
+    const outputFile = path.join(outputDir, relativePath);
+
+    ensureDirExists(path.dirname(outputFile));
+    fs.copyFileSync(inputFile, outputFile);
+
+    console.log(`📜 Copied JS: ${relativePath}`);
+  }
+}
+
+function prefixAssetPathsInFile(filePath: string) {
+  const ASSET_PATH = process.env.ASSET_PATH || "";
+  let content = fs.readFileSync(filePath, "utf-8");
+
+  // Replace "/assets/..." inside string literals with prefixed path
+  // Match quotes + /assets/ at start of string
+  content = content.replace(/(["'`])\/assets\//g, `$1/${ASSET_PATH}/`);
+
+  fs.writeFileSync(filePath, content, "utf-8");
+  console.log(`Prefixed asset paths in ${filePath}`);
+}
+
+function processAllJsFiles(dir: string) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      processAllJsFiles(fullPath);
+    } else if (entry.name.endsWith(".js")) {
+      prefixAssetPathsInFile(fullPath);
+    }
+  }
+}
+
+
+/**
+ * Main function
+ */
+function processOutput() {
+  const inputDir = path.resolve("dist");
+  const outputDir = path.resolve("output");
+  const assetsSrc = path.join(inputDir, "assets");
+  const assetsDest = path.join(outputDir, "assets");
+
+  if (!fs.existsSync(inputDir)) {
+    console.error(`❌ Input directory not found: ${inputDir}`);
+    process.exit(1);
+  }
+
+  // 🧹 Clear output directory before writing
+  if (fs.existsSync(outputDir)) {
+    console.log("🧹 Clearing output directory...");
+    clearDirectory(outputDir);
+  } else {
+    ensureDirExists(outputDir);
+  }
+
+  console.log("⚙️ Processing HTML files...");
+  processAllHTML(inputDir, outputDir);
+
+  console.log("📦 Copying assets...");
+  copyDirectory(assetsSrc, assetsDest);
+
+  console.log("📜 Copying JavaScript files...");
+  copyAllJSFiles(inputDir, outputDir);
+
+  console.log("📜 Processing asset paths...");
+  processAllJsFiles("output");
+
+  console.log("✅ Done!");
+}
+
+processOutput();