Build your Own Instance Tutorial
Last modified by Manuel Leduc on 2025/01/27 16:51
- Preliminary notes
- Create a project directory
- Initialize a node project
- Add the dependencies
- Initialize the project code
- Patch avvvatars-vue.patch
- Build and run
Preliminary notes
- all the instructions below are using pnpm, but can easily be ported to npm to yarn.
- all the instructions are for Linux but nothing prevents from working on MacOS or Windows
- vite and typescript are used to build the project. Those dependencies are used to make things easier but feel free to use you favorite build tools.
- Knowledge of the node and typescript ecosystems are expected
Create a project directory
# Create a project directory and move into it
mkdir cristal-web
cd cristal-webInitialize a node project
pnpm initAdd the dependencies
# Cristal dependencies
pnpm add @xwiki/cristal-lib @xwiki/cristal-browser-default reflect-metadata
# Build dependencies
pnpm add -D vite typescriptInitialize the project code
Minimal HTML
Create index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Cristal</title>
</head>
<body>
<!-- DOM element to attach Cristal UI. -->
<div id="xwCristalApp" class="xw-cristal"></div>
</body>
</html>Minimal typescript
Import the index.ts script.
Index: index.html
===================================================================
diff --git a/index.html b/index.html
--- a/index.html
+++ b/index.html
@@ -7,5 +7,6 @@
<body>
<!-- DOM element to attach Cristal UI. -->
<div id="xwCristalApp" class="xw-cristal"></div>
+<script type="module" src="./index.ts"></script>
</body>
</html>
Create index.ts and define the minimal instruction to initialize Cristal.
// index.ts
import 'reflect-metadata'
import {CristalAppLoader} from "@xwiki/cristal-lib";
import {ComponentInit as BrowserComponentInit} from "@xwiki/cristal-browser-default";
CristalAppLoader.init([], async () => {
return {}
}, true, false, "XWiki", (container) => {
new BrowserComponentInit(container)
})Minimal configuration
Introduce a configuration. In this example, we use a configuration for XWiki, but other Backends are available.
The XWiki instance is expected to run on port 8080. The XWiki instance must have some Cristal specific configuration.
Index: index.ts
<+>UTF-8
===================================================================
diff --git a/index.ts b/index.ts
--- a/index.ts
+++ b/index.ts
@@ -21,8 +21,22 @@
import {CristalAppLoader} from "@xwiki/cristal-lib";
import {ComponentInit as BrowserComponentInit} from "@xwiki/cristal-browser-default";
+const config: Record<string, any> = {
+ "XWiki": {
+ "name": "XWiki",
+ "configType": "XWiki",
+ "serverRendering": false,
+ "offline": false,
+ "baseURL": "http://localhost:8080/xwiki",
+ "baseRestURL": "/rest/cristal/page?media=json",
+ "homePage": "Main.WebHome",
+ "designSystem": "vuetify"
+ }
+};
+
+
CristalAppLoader.init([], async () => {
- return {}
+ return config
}, true, false, "XWiki", (container) => {
new BrowserComponentInit(container)
})
Cristal <0.14
Patch avvvatars-vue.patch
Index: package.json
<+>UTF-8
===================================================================
diff --git a/package.json b/package.json
--- a/package.json
+++ b/package.json
@@ -15,5 +15,10 @@
"devDependencies": {
"typescript": "5.7.2",
"vite": "6.0.6"
+ },
+ "pnpm": {
+ "patchedDependencies": {
+ "avvvatars-vue": "avvvatars-vue.patch"
+ }
}
}
Create avvvatars-vue.patch.
diff --git a/package.json b/package.json
index 6c5e73c11a121948840d6f082410117d97401641..407678843d78098acc9423809f5af3406c88bbf3 100644
--- a/package.json
+++ b/package.json
@@ -20,12 +20,12 @@
],
"exports": {
".": {
- "types": "./dist/index.d.ts",
- "import": "./dist/index.mjs"
+ "types": "./dist/src/index.d.ts",
+ "import": "./dist/index.es.js"
}
},
- "module": "./dist/index.mjs",
- "types": "./dist/index.d.ts",
+ "module": "./dist/index.es.js",
+ "types": "./dist/src/index.d.ts",
"files": [
"dist"
],
Build and run
# Build
pnpm exec vite build
# Run
pnpm exec vite preview
# Start the XWiki instance
# Access Cristal at http://localhost:4173/ (or the URL displayed by the preview command)
This project is being financed by the French State as part of the France 2030 program
Ce projet est financé par l’État Français dans le cadre de France 2030
