chore(sdk): Create Astro Example for UVE (#29665)

# Proposed changes 1. Add new Astro project under `examples` folder 2. Install necessary dependencies to make it work as the other examples (Tailwind and Vercel plugin) 3. Add env file 4. Install `client` and `react` SDKs 5. Create React components to interop Astro with the React SDK 6. Clean the project by creating types and centralizing logic 7. Update readme file to add steps of how to set it up ## Screenshot https://github.com/user-attachments/assets/4d5f151e-169d-4bfa-b62d-b2447fe84f23 --------- Co-authored-by: Freddy Montes <[email protected]>
dotCMS · Sep 4, 2024 · b658fea · b658fea
1 parent bb116fe
commit b658fea
Show file tree

Hide file tree

Showing 45 changed files with 9,960 additions and 24 deletions.
diff --git a/core-web/libs/sdk/angular/package.json b/core-web/libs/sdk/angular/package.json
@@ -1,11 +1,11 @@
 {
   "name": "@dotcms/angular",
-  "version": "0.0.1-alpha.35",
+  "version": "0.0.1-alpha.36",
   "peerDependencies": {
     "@angular/common": "^17.1.0",
     "@angular/core": "^17.1.0",
     "@angular/router": "^17.1.0",
-    "@dotcms/client": "0.0.1-alpha.35",
+    "@dotcms/client": "0.0.1-alpha.36",
     "@tinymce/tinymce-angular": "^8.0.0",
     "rxjs": "^7.8.0"
   },

diff --git a/core-web/libs/sdk/client/package.json b/core-web/libs/sdk/client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/client",
-  "version": "0.0.1-alpha.35",
+  "version": "0.0.1-alpha.36",
   "description": "Official JavaScript library for interacting with DotCMS REST APIs.",
   "repository": {
     "type": "git",

diff --git a/core-web/libs/sdk/client/src/lib/utils/page/common-utils.ts b/core-web/libs/sdk/client/src/lib/utils/page/common-utils.ts
@@ -1,27 +1,36 @@
 interface PageRequestParamsProps {
     path: string;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    params: { [key: string]: any } | undefined; // QueryParams are typed as `any` in frameworks
+    params: { [key: string]: any } | undefined | URLSearchParams; // QueryParams are typed as `any` in frameworks
 }
 
-export const getPageRequestParams = ({ path = '', params = {} }: PageRequestParamsProps) => {
+export const getPageRequestParams = ({
+    path = '',
+    params = {}
+}: PageRequestParamsProps): {
+    path: string;
+    [key: string]: string | number;
+} => {
+    const copiedParams: PageRequestParamsProps['params'] =
+        params instanceof URLSearchParams ? Object.fromEntries(params.entries()) : { ...params };
+
     const finalParams: Record<string, unknown> = {};
-    const dotMarketingPersonaId = params['com.dotmarketing.persona.id'] || '';
+    const dotMarketingPersonaId = copiedParams['com.dotmarketing.persona.id'] || '';
 
-    if (params['mode']) {
-        finalParams['mode'] = params['mode'];
+    if (copiedParams['mode']) {
+        finalParams['mode'] = copiedParams['mode'];
     }
 
-    if (params['language_id']) {
-        finalParams['language_id'] = params['language_id'];
+    if (copiedParams['language_id']) {
+        finalParams['language_id'] = copiedParams['language_id'];
     }
 
-    if (params['variantName']) {
-        finalParams['variantName'] = params['variantName'];
+    if (copiedParams['variantName']) {
+        finalParams['variantName'] = copiedParams['variantName'];
     }
 
-    if (params['personaId'] || dotMarketingPersonaId) {
-        finalParams['personaId'] = params['personaId'] || dotMarketingPersonaId;
+    if (copiedParams['personaId'] || dotMarketingPersonaId) {
+        finalParams['personaId'] = copiedParams['personaId'] || dotMarketingPersonaId;
     }
 
     return {

diff --git a/core-web/libs/sdk/experiments/package.json b/core-web/libs/sdk/experiments/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/experiments",
-  "version": "0.0.1-alpha.35",
+  "version": "0.0.1-alpha.36",
   "description": "Official JavaScript library to use Experiments with DotCMS.",
   "repository": {
     "type": "git",
@@ -25,6 +25,6 @@
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18",
-    "@dotcms/client": "0.0.1-alpha.35"
+    "@dotcms/client": "0.0.1-alpha.36"
   }
 }
diff --git a/core-web/libs/sdk/react/package.json b/core-web/libs/sdk/react/package.json
@@ -1,10 +1,10 @@
 {
   "name": "@dotcms/react",
-  "version": "0.0.1-alpha.35",
+  "version": "0.0.1-alpha.36",
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18",
-    "@dotcms/client": "0.0.1-alpha.35",
+    "@dotcms/client": "0.0.1-alpha.36",
     "@tinymce/tinymce-react": "^5.1.1"
   },
   "description": "Official React Components library to render a dotCMS page.",

diff --git a/examples/angular/package.json b/examples/angular/package.json
@@ -18,8 +18,8 @@
     "@angular/platform-browser": "^17.1.0",
     "@angular/platform-browser-dynamic": "^17.1.0",
     "@angular/router": "^17.1.0",
-    "@dotcms/angular": "0.0.1-alpha.35",
-    "@dotcms/client": "0.0.1-alpha.35",
+    "@dotcms/angular": "0.0.1-alpha.36",
+    "@dotcms/client": "0.0.1-alpha.36",
     "rxjs": "~7.8.0",
     "tslib": "^2.3.0",
     "zone.js": "~0.14.2"

diff --git a/examples/astro/.env.local.example b/examples/astro/.env.local.example
@@ -0,0 +1,11 @@
+PUBLIC_DOTCMS_AUTH_TOKEN=YOUR_API_TOKEN
+PUBLIC_DOTCMS_HOST=http://localhost:8080
+PUBLIC_DOTCMS_SITE_ID=your-dotcms-site-id
+PUBLIC_EXPERIMENTS_API_KEY=analytic-api-key-from-dotcms-portlet
+PUBLIC_EXPERIMENTS_DEBUG=true
+# If your local dotcms instance is running in https, this setting allows Node.js to connect to servers with invalid SSL certificates.
+# For testing purposes only.
+NODE_TLS_REJECT_UNAUTHORIZED=0
+
+
+
diff --git a/examples/astro/.gitignore b/examples/astro/.gitignore
@@ -0,0 +1,25 @@
+# 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
+.env.local
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/
diff --git a/examples/astro/.prettierrc.mjs b/examples/astro/.prettierrc.mjs
@@ -0,0 +1,12 @@
+/** @type {import("prettier").Config} */
+export default {
+  plugins: ["prettier-plugin-astro"],
+  overrides: [
+    {
+      files: "*.astro",
+      options: {
+        parser: "astro",
+      },
+    },
+  ],
+};
diff --git a/examples/astro/README.md b/examples/astro/README.md
@@ -0,0 +1,50 @@
+# dotCMS Astro Example
+
+DotCMS provides a Astro example that shows how to build dotCMS pages heedlessly with Astro JavaScript framework.
+
+## What do you need?
+
+1. A dotCMS instance or you can use https://demo.dotcms.com
+2. A valid AUTH token for the target instance (see: https://auth.dotcms.com/docs/latest/rest-api-authentication#creating-an-api-token-in-the-ui)
+3. A valid Site Identifier where your page is located (see: https://www.dotcms.com/docs/latest/multi-site-management#multi-site-management)
+4. Node js 18+ and npm installed
+5. Terminal
+6. And a code editor.
+
+### Create the new Astro application
+
+Open your terminal and let’s create the Astro app by running the following:
+
+```bash
+npm create astro@latest -- --template dotcms/core/examples/astro
+```
+
+Follow the Astro setup steps after it pulls the example.
+
+## Add the dotCMS configuration
+
+Now we need to tell the Astro app what dotCMS instance is going to use to get the data to build its pages.
+
+1. Open the folder where you created the project in your code editor
+2. In the root, find the file `.env.local.example` and rename to `.env.local`
+3. Open the .env.local file and update the environment variable:
+
+   - `PUBLIC_DOTCMS_AUTH_TOKEN` this is the auth token for dotCMS, you can use the dotCMS UI to create one.
+   - `PUBLIC_DOTCMS_HOST` this is the instance of dotCMS where your pages and content lives (license needed) if you don’t have one, you can use [https://demo.dotcms.com](https://demo.dotcms.com) (be careful it restarts every 24h).
+   - `PUBLIC_DOTCMS_SITE_ID` this is the identifier of the Site you are going to use for your website you can find it by going to Settings > Sites. Once there follow the next steps:
+
+     1. Select the desired Site (A modal should be opened)
+     2. Go to the History Tab
+     3. Copy the `Identifier` that appears in the top of the tab
+
+## Run the app
+
+Once all the configuration is in place, it is time to run the web app.
+
+1. Go back to your terminal and from the folder you created the project
+2. Run `npm run dev`
+3. Open http://localhost:4321 in your browser (Verify the port Astro is using, 4321 is the default but it can change)
+
+🎉 And that’s it.
+
+Consider that if you go to `localhost:4321/about`, the page `/about` needs to exist in your dotCMS instance.
diff --git a/examples/astro/astro.config.mjs b/examples/astro/astro.config.mjs
@@ -0,0 +1,12 @@
+import { defineConfig } from "astro/config";
+import react from "@astrojs/react";
+import tailwind from "@astrojs/tailwind";
+
+import vercel from "@astrojs/vercel/serverless";
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [react(), tailwind()],
+  output: "server",
+  adapter: vercel(),
+});