create-outsystems-astro 0.10.0 → 0.11.0

package/integrations/tsconfig.json

@@ -3,6 +3,7 @@
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "target": "ESNext",
+    "esModuleInterop": true,
     "declaration": true,
     "declarationMap": true,
     "outDir": "dist",
@@ -10,6 +11,6 @@
     "strict": true,
     "skipLibCheck": true
   },
-  "include": ["html/**/*.ts"],
+  "include": ["html/**/*.ts", "twig/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }

package/integrations/twig/client.ts

@@ -0,0 +1,34 @@
+import Twig from "twig";
+
+const client_default =
+  (element: HTMLElement) =>
+  (
+    Component: unknown,
+    props: Record<string, unknown>,
+    { client }: { client: string },
+  ) => {
+    if (client !== "only" && !element.hasAttribute("ssr")) return;
+
+    let template: string;
+    if (typeof Component === "string") {
+      template = Component;
+    } else if (typeof Component === "function") {
+      template = (Component as (p: Record<string, unknown>) => string)({
+        ...props,
+      });
+    } else {
+      template = "";
+    }
+
+    const html = Twig.twig({ data: template }).render({ ...props });
+
+    element.innerHTML = html;
+
+    element.querySelectorAll("script").forEach((oldScript) => {
+      const newScript = document.createElement("script");
+      newScript.textContent = oldScript.textContent;
+      oldScript.parentNode?.replaceChild(newScript, oldScript);
+    });
+  };
+
+export default client_default;

package/integrations/twig/index.ts

@@ -0,0 +1,185 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { AstroIntegration, AstroRenderer } from "astro";
+
+const VIRTUAL_SERVER_ID = "virtual:islands/twig/server-with-filter";
+const RESOLVED_VIRTUAL_SERVER_ID = `\0${VIRTUAL_SERVER_ID}`;
+
+function getRenderer(filtered: boolean): AstroRenderer {
+  return {
+    clientEntrypoint: "islands-integrations/twig/client",
+    name: "islands/twig",
+    serverEntrypoint: filtered
+      ? VIRTUAL_SERVER_ID
+      : "islands-integrations/twig/server",
+  };
+}
+
+export const getContainerRenderer = (): AstroRenderer => getRenderer(false);
+
+export interface Options {
+  exclude?: string[];
+  include?: string[];
+  namespaces?: Record<string, string>;
+}
+
+type Namespaces = Record<string, string>;
+
+function normalizeNamespaces(
+  namespaces: Record<string, string> | undefined,
+  root: string,
+): Namespaces {
+  const normalized: Namespaces = {};
+  for (const [name, dir] of Object.entries(namespaces ?? {})) {
+    normalized[name.replace(/^@/, "")] = path.resolve(root, dir);
+  }
+  return normalized;
+}
+
+const NAMESPACE_PATH = /^@([^/]+)\/(.*)$/;
+
+function resolveIncludePath(
+  includePath: string,
+  dir: string,
+  namespaces: Namespaces,
+): string {
+  const match = NAMESPACE_PATH.exec(includePath);
+  if (!match) return path.resolve(dir, includePath);
+
+  const [, name, rest] = match;
+  const base = namespaces[name];
+  if (!base) {
+    throw new Error(
+      `Twig namespace "@${name}" is not configured. Add it to the \`namespaces\` option of the twig() integration.`,
+    );
+  }
+  return path.resolve(base, rest);
+}
+
+function twigFilterPlugin(include?: string[], exclude?: string[]) {
+  return {
+    load(id: string) {
+      if (id !== RESOLVED_VIRTUAL_SERVER_ID) return;
+      return [
+        `import { createRenderer } from "islands-integrations/twig/server";`,
+        `export default createRenderer(${JSON.stringify(include)}, ${JSON.stringify(exclude)});`,
+      ].join("\n");
+    },
+    name: "islands/twig/filter",
+    resolveId(id: string) {
+      if (id === VIRTUAL_SERVER_ID) return RESOLVED_VIRTUAL_SERVER_ID;
+    },
+  };
+}
+
+const INCLUDE_TAG = /\{%-?\s*include\s+(['"])([^'"]+)\1([^%]*?)-?%\}/g;
+
+interface IncludeModifiers {
+  ignoreMissing: boolean;
+  only: boolean;
+  withExpr?: string;
+}
+
+function applyContextScope(
+  body: string,
+  { only, withExpr }: IncludeModifiers,
+): string {
+  if (!withExpr && !only) return body;
+  const vars = withExpr ?? "{}";
+  const onlyFlag = only ? " only" : "";
+  return `{% with ${vars}${onlyFlag} %}${body}{% endwith %}`;
+}
+
+function inlineIncludes(
+  filepath: string,
+  ancestors: string[],
+  namespaces: Namespaces,
+  onInclude?: (target: string) => void,
+): string {
+  const resolved = path.resolve(filepath);
+  if (ancestors.includes(resolved)) {
+    throw new Error(
+      `Twig include cycle detected: ${[...ancestors, resolved].join(" -> ")}`,
+    );
+  }
+
+  const source = fs.readFileSync(resolved, "utf-8");
+  const dir = path.dirname(resolved);
+  const trail = [...ancestors, resolved];
+
+  return source.replace(
+    INCLUDE_TAG,
+    (_match, _quote, includePath, modifiers) => {
+      const parsed = parseModifiers(modifiers);
+      const target = resolveIncludePath(includePath, dir, namespaces);
+      if (!fs.existsSync(target)) {
+        if (parsed.ignoreMissing) return "";
+        throw new Error(
+          `Twig include "${includePath}" not found (referenced from ${resolved}).`,
+        );
+      }
+      onInclude?.(target);
+      const body = inlineIncludes(target, trail, namespaces, onInclude);
+      return applyContextScope(body, parsed);
+    },
+  );
+}
+
+function parseModifiers(modifiers: string): IncludeModifiers {
+  const ignoreMissing = /\bignore\s+missing\b/.test(modifiers);
+  let rest = modifiers.replace(/\bignore\s+missing\b/, " ");
+
+  const only = /\bonly\s*$/.test(rest);
+  rest = rest.replace(/\bonly\s*$/, " ");
+
+  const withMatch = /\bwith\b([\s\S]*)$/.exec(rest);
+  const withExpr = withMatch ? withMatch[1].trim() : undefined;
+
+  return { ignoreMissing, only, withExpr: withExpr || undefined };
+}
+
+function twigLoaderPlugin(namespaces: Namespaces) {
+  return {
+    enforce: "pre" as const,
+    load(this: { addWatchFile?: (id: string) => void }, id: string) {
+      const filepath = id.split("?")[0];
+      if (!filepath.endsWith(".twig")) return;
+      const source = inlineIncludes(filepath, [], namespaces, (target) =>
+        this.addWatchFile?.(target),
+      );
+      return {
+        code: `export default ${JSON.stringify(source)};`,
+        map: null,
+      };
+    },
+    name: "islands/twig/loader",
+  };
+}
+
+export default function (options: Options = {}): AstroIntegration {
+  const { exclude, include, namespaces } = options;
+  const filtered = !!(include?.length || exclude?.length);
+
+  return {
+    hooks: {
+      "astro:config:setup": ({ addRenderer, config, updateConfig }) => {
+        addRenderer(getRenderer(filtered));
+        const resolvedNamespaces = normalizeNamespaces(
+          namespaces,
+          fileURLToPath(config.root),
+        );
+        const loader = twigLoaderPlugin(resolvedNamespaces);
+        updateConfig({
+          vite: {
+            plugins: filtered
+              ? [loader, twigFilterPlugin(include, exclude)]
+              : [loader],
+          },
+        });
+      },
+    },
+    name: "islands/twig",
+  };
+}

package/integrations/twig/server.ts

@@ -0,0 +1,54 @@
+import type {
+  AstroComponentMetadata,
+  NamedSSRLoadedRendererValue,
+} from "astro";
+
+export function createRenderer(
+  include?: string[],
+  exclude?: string[],
+): NamedSSRLoadedRendererValue {
+  return {
+    check: async (
+      Component: unknown,
+      _props: unknown,
+      _slots: unknown,
+      metadata?: AstroComponentMetadata,
+    ) => {
+      const url = metadata?.componentUrl;
+      if (url) {
+        if (include && !matchesPatterns(url, include)) return false;
+        if (exclude && matchesPatterns(url, exclude)) return false;
+      }
+      return checkComponent(Component);
+    },
+    name: "islands/twig",
+    renderToStaticMarkup,
+    supportsAstroStaticSlot: false,
+  };
+}
+
+async function checkComponent(Component: unknown): Promise<boolean> {
+  if (typeof Component === "string") return true;
+  if (typeof Component === "function") {
+    try {
+      const result = (Component as (p: Record<string, unknown>) => unknown)({});
+      return typeof result === "string";
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+function matchesPatterns(url: string, patterns: string[]): boolean {
+  return patterns.some((pattern) => {
+    const prefix = pattern.replace(/\/?\*+$/, "");
+    return url.includes(prefix);
+  });
+}
+
+async function renderToStaticMarkup(): Promise<{ html: string }> {
+  return { html: "" };
+}
+
+export default createRenderer();

package/integrations/yarn.lock

@@ -104,6 +104,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@babel/runtime@npm:^7.8.4":
+  version: 7.29.2
+  resolution: "@babel/runtime@npm:7.29.2"
+  checksum: 10c0/30b80a0140d16467792e1bbeb06f655b0dab70407da38dfac7fedae9c859f9ae9d846ef14ad77bd3814c064295fe9b1bc551f1541ea14646ae9f22b71a8bc17a
+  languageName: node
+  linkType: hard
+
 "@babel/types@npm:^7.29.0":
   version: 7.29.0
   resolution: "@babel/types@npm:7.29.0"
@@ -1121,6 +1128,22 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/node@npm:^25.9.1":
+  version: 25.9.1
+  resolution: "@types/node@npm:25.9.1"
+  dependencies:
+    undici-types: "npm:>=7.24.0 <7.24.7"
+  checksum: 10c0/9a04682842bebbcf21a1779dfeab9aa733d7bd7bbc0a0edb641ab3a9a3d43eac543225acf669c334f458f1956443ebc072bc3c72840c543b8b356cab5c82d456
+  languageName: node
+  linkType: hard
+
+"@types/twig@npm:^1.12.17":
+  version: 1.12.17
+  resolution: "@types/twig@npm:1.12.17"
+  checksum: 10c0/a54d62abb979ecc81707c7da9ffe641cdbb12c5e73d782c5fbed69c41123d7c2142c8c79fe7a92295bc13eea7abbafd68863e5f0eb3f54094a26b179e3a2d653
+  languageName: node
+  linkType: hard
+
 "@types/unist@npm:*, @types/unist@npm:^3.0.0":
   version: 3.0.3
   resolution: "@types/unist@npm:3.0.3"
@@ -2802,6 +2825,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"foreachasync@npm:^3.0.0":
+  version: 3.0.0
+  resolution: "foreachasync@npm:3.0.0"
+  checksum: 10c0/8ad877008da351fa78939e850c6014e94b8b9c6de3d12751b2b906ef96f8c80945310d998b2a704854e126c508237dc9951f6900685ccc42c93db15b09a0c4b3
+  languageName: node
+  linkType: hard
+
 "fsevents@npm:~2.3.2, fsevents@npm:~2.3.3":
   version: 2.3.3
   resolution: "fsevents@npm:2.3.3"
@@ -3570,6 +3600,8 @@ __metadata:
   dependencies:
     "@eslint/compat": "npm:^2.1.0"
     "@eslint/js": "npm:^9.39.4"
+    "@types/node": "npm:^25.9.1"
+    "@types/twig": "npm:^1.12.17"
     astro: "npm:^6.3.7"
     better-npm-audit: "npm:^3.11.0"
     eslint: "npm:^9.39.4"
@@ -3579,6 +3611,7 @@ __metadata:
     eslint-plugin-perfectionist: "npm:^5.9.0"
     globals: "npm:^17.6.0"
     prettier: "npm:^3.8.3"
+    twig: "npm:^3.0.0"
     typescript: "npm:^5.9.3"
     typescript-eslint: "npm:^8.59.4"
   languageName: unknown
@@ -3669,6 +3702,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"locutus@npm:^3.0.9":
+  version: 3.0.36
+  resolution: "locutus@npm:3.0.36"
+  checksum: 10c0/54a04ecddeaeadd924f2362c31d888e333bb717bd48dd9d40ac6ddccb352a924791223e09b782d03196808c1404a1f74210a388ce4475c3650dcb8d7b0a75730
+  languageName: node
+  linkType: hard
+
 "lodash.get@npm:^4.4.2":
   version: 4.4.2
   resolution: "lodash.get@npm:4.4.2"
@@ -4271,7 +4311,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"minimatch@npm:^10.2.2":
+"minimatch@npm:^10, minimatch@npm:^10.2.2":
   version: 10.2.5
   resolution: "minimatch@npm:10.2.5"
   dependencies:
@@ -5713,6 +5753,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"twig@npm:^3.0.0":
+  version: 3.0.0
+  resolution: "twig@npm:3.0.0"
+  dependencies:
+    "@babel/runtime": "npm:^7.8.4"
+    locutus: "npm:^3.0.9"
+    minimatch: "npm:^10"
+    walk: "npm:2.3.x"
+  bin:
+    twigjs: bin/twigjs
+  checksum: 10c0/a727b665d34c9b7db9cf5fa99072472ef1dd9291d6f29a4b1de88ca95493d16c667f47d7e87f4aaea05275ea184f6550dc3c32cb42026b819d154690f48cff76
+  languageName: node
+  linkType: hard
+
 "type-check@npm:^0.4.0, type-check@npm:~0.4.0":
   version: 0.4.0
   resolution: "type-check@npm:0.4.0"
@@ -5843,6 +5897,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"undici-types@npm:>=7.24.0 <7.24.7":
+  version: 7.24.6
+  resolution: "undici-types@npm:7.24.6"
+  checksum: 10c0/d9cd8befb643ac904615c280a095ba4240531f6bb4a5e75a22a7483630ca8d3f1016d2ab6ace6ceda1f63b3a2db2fe037fafe121d6917a0187573aa548ff78ca
+  languageName: node
+  linkType: hard
+
 "undici@npm:^6.25.0":
   version: 6.25.0
   resolution: "undici@npm:6.25.0"
@@ -6151,6 +6212,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"walk@npm:2.3.x":
+  version: 2.3.15
+  resolution: "walk@npm:2.3.15"
+  dependencies:
+    foreachasync: "npm:^3.0.0"
+  checksum: 10c0/c390221ff6fdb8e95f9b03d90fa9980edc2c01ce9efac44c0ade2036ee2823bf2bc9abfae388bdf64ab59e9262610e7cf6634ad54acac018e62621b85edad2cf
+  languageName: node
+  linkType: hard
+
 "web-namespaces@npm:^2.0.0":
   version: 2.0.1
   resolution: "web-namespaces@npm:2.0.1"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-outsystems-astro",
   "type": "module",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Create an OutSystems Astro Island project to import as a component into your OutSystems application",
   "repository": {
     "type": "git",

package/template/AGENTS.md

@@ -11,6 +11,7 @@
   - React - Documentation available at https://docs.astro.build/en/guides/integrations-guide/react/
   - SolidJS - Documentation available at https://docs.astro.build/en/guides/integrations-guide/solid-js/
   - Svelte - Documentation availabe at https://docs.astro.build/en/guides/integrations-guide/svelte/
+  - Twig - Documentation available at https://hs2323.github.io/create-outsystems-astro/guides/integrations/twig/
   - Vue - Documentation available at https://docs.astro.build/en/guides/integrations-guide/vue/
 - Prefer to use TypeScript when possible.
 
@@ -44,6 +45,7 @@ In OutSystems Developer Cloud, the Islands library is available at https://www.o
   - React: `client:only="react"`
   - SolidJS: `client:only="solid-js"`
   - Svelte: `client:only="svelte"`
+  - Twig: `client:load`
   - Vue: `client:only="vue"`
 
 ### Components
@@ -94,6 +96,10 @@ Angular does not support the use of slots. Any use of slots with Angular should
 
 The HTML integration does not support the use of slots. Any use of slots with the HTML integration should be discouraged.
 
+##### Twig
+
+The Twig integration does not support the use of slots. Any use of slots with the Twig integration should be discouraged. Pass content in as props and render it with `{{ }}` instead.
+
 ##### Preact
 
 - In Preact, 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:
@@ -406,6 +412,47 @@ export default function Counter({}) {
 <div>{$nanoStoreValue}</div>
 ```
 
+#### Twig
+
+Like the HTML integration, Twig does not use a Nano Stores binding library. Set up a compatible store on `window.Stores` inside the component's `<script>` tag and subscribe to it directly.
+
+```html
+<div class="nanostore-value"></div>
+<script>
+  const nanostoreEl = container.querySelector(".nanostore-value");
+
+  if (!window.Stores) window.Stores = {};
+  if (!window.Stores["twigStore"]) {
+    let _value = "Test Value";
+    const _subs = [];
+    window.Stores["twigStore"] = {
+      get: function () {
+        return _value;
+      },
+      set: function (v) {
+        _value = v;
+        _subs.forEach(function (fn) {
+          fn(v);
+        });
+      },
+      subscribe: function (fn) {
+        fn(_value);
+        _subs.push(fn);
+        return function () {
+          _subs.splice(_subs.indexOf(fn), 1);
+        };
+      },
+    };
+  }
+
+  const store = window.Stores["twigStore"];
+  nanostoreEl.textContent = store.get();
+  store.subscribe(function (value) {
+    nanostoreEl.textContent = value;
+  });
+</script>
+```
+
 #### Vue
 
 ```vue

package/template/astro.config.mjs

@@ -7,6 +7,7 @@ import svelte from "@astrojs/svelte";
 import vue from "@astrojs/vue";
 import { defineConfig } from "astro/config";
 import html from "islands-integrations/html";
+import twig from "islands-integrations/twig";
 
 // https://astro.build/config
 export default defineConfig({
@@ -39,6 +40,9 @@ export default defineConfig({
     svelte({
       include: ["src/framework/svelte/*"],
     }),
+    twig({
+      include: ["src/framework/twig/*"],
+    }),
     vue({
       include: ["src/framework/vue/*"],
     }),