Skip to Content
Last modified by Manuel Leduc on 2025/01/27 16:51
Show last authors
1 {{toc/}}
2
3 = Preliminary notes =
4
5 * all the instructions below are using pnpm, but can easily be ported to [[npm>>https://docs.npmjs.com/cli/]] to [[yarn>>https://yarnpkg.com/]].
6 * all the instructions are for Linux but nothing prevents from working on MacOS or Windows
7 * [[vite>>https://vite.dev/]] and [[typescript>>https://www.typescriptlang.org/]] are used to build the project. Those dependencies are used to make things easier but feel free to use you favorite build tools.
8 * Knowledge of the node and typescript ecosystems are expected
9
10 = Create a project directory =
11
12 {{code language="bash"}}
13 # Create a project directory and move into it
14 mkdir cristal-web
15 cd cristal-web
16 {{/code}}
17
18 = Initialize a node project =
19
20 {{code language="bash"}}
21 pnpm init
22 {{/code}}
23
24 = Add the dependencies =
25
26 {{code language="bash"}}
27 # Cristal dependencies
28 pnpm add @xwiki/cristal-lib @xwiki/cristal-browser-default reflect-metadata
29 # Build dependencies
30 pnpm add -D vite typescript
31 {{/code}}
32
33 = Initialize the project code =
34
35 == Minimal HTML ==
36
37 Create ##index.html##
38
39 {{code language="html"}}
40 <!DOCTYPE html>
41 <html lang="en">
42 <head>
43 <meta charset="UTF-8">
44 <title>Cristal</title>
45 </head>
46 <body>
47 <!-- DOM element to attach Cristal UI. -->
48 <div id="xwCristalApp" class="xw-cristal"></div>
49 </body>
50 </html>
51 {{/code}}
52
53 == Minimal typescript ==
54
55 Import the ##index.ts## script.
56
57 {{code language="diff"}}
58 Index: index.html
59 ===================================================================
60 diff --git a/index.html b/index.html
61 --- a/index.html
62 +++ b/index.html
63 @@ -7,5 +7,6 @@
64 <body>
65 <!-- DOM element to attach Cristal UI. -->
66 <div id="xwCristalApp" class="xw-cristal"></div>
67 +<script type="module" src="./index.ts"></script>
68 </body>
69 </html>
70
71 {{/code}}
72
73 Create ##index.ts## and define the minimal instruction to initialize Cristal.
74
75 {{code language="typescript"}}
76 // index.ts
77 import 'reflect-metadata'
78 import {CristalAppLoader} from "@xwiki/cristal-lib";
79 import {ComponentInit as BrowserComponentInit} from "@xwiki/cristal-browser-default";
80
81 CristalAppLoader.init([], async () => {
82 return {}
83 }, true, false, "XWiki", (container) => {
84 new BrowserComponentInit(container)
85 })
86 {{/code}}
87
88 == Minimal configuration ==
89
90 Introduce a configuration. In this example, we use a configuration for [[XWiki>>Backends.XWiki.WebHome]], but other [[Backends>>Backends.WebHome]] are available.
91
92 The XWiki instance is expected to run on port 8080. The XWiki instance must have some [[Cristal specific configuration>>doc:Backends.XWiki.WebHome||anchor="HSetup"]].
93
94 {{code language="diff"}}
95 Index: index.ts
96 <+>UTF-8
97 ===================================================================
98 diff --git a/index.ts b/index.ts
99 --- a/index.ts
100 +++ b/index.ts
101 @@ -21,8 +21,22 @@
102 import {CristalAppLoader} from "@xwiki/cristal-lib";
103 import {ComponentInit as BrowserComponentInit} from "@xwiki/cristal-browser-default";
104
105 +const config: Record<string, any> = {
106 + "XWiki": {
107 + "name": "XWiki",
108 + "configType": "XWiki",
109 + "serverRendering": false,
110 + "offline": false,
111 + "baseURL": "http://localhost:8080/xwiki",
112 + "baseRestURL": "/rest/cristal/page?media=json",
113 + "homePage": "Main.WebHome",
114 + "designSystem": "vuetify"
115 + }
116 +};
117 +
118 +
119 CristalAppLoader.init([], async () => {
120 - return {}
121 + return config
122 }, true, false, "XWiki", (container) => {
123 new BrowserComponentInit(container)
124 })
125
126 {{/code}}
127
128 {{version product="Cristal" before="0.14"}}
129 = Patch avvvatars-vue.patch =
130
131 {{code language="diff"}}
132 Index: package.json
133 <+>UTF-8
134 ===================================================================
135 diff --git a/package.json b/package.json
136 --- a/package.json
137 +++ b/package.json
138 @@ -15,5 +15,10 @@
139 "devDependencies": {
140 "typescript": "5.7.2",
141 "vite": "6.0.6"
142 + },
143 + "pnpm": {
144 + "patchedDependencies": {
145 + "avvvatars-vue": "avvvatars-vue.patch"
146 + }
147 }
148 }
149
150 {{/code}}
151
152 Create ##avvvatars-vue.patch##.
153
154 {{code language="diff"}}
155 diff --git a/package.json b/package.json
156 index 6c5e73c11a121948840d6f082410117d97401641..407678843d78098acc9423809f5af3406c88bbf3 100644
157 --- a/package.json
158 +++ b/package.json
159 @@ -20,12 +20,12 @@
160 ],
161 "exports": {
162 ".": {
163 - "types": "./dist/index.d.ts",
164 - "import": "./dist/index.mjs"
165 + "types": "./dist/src/index.d.ts",
166 + "import": "./dist/index.es.js"
167 }
168 },
169 - "module": "./dist/index.mjs",
170 - "types": "./dist/index.d.ts",
171 + "module": "./dist/index.es.js",
172 + "types": "./dist/src/index.d.ts",
173 "files": [
174 "dist"
175 ],
176
177 {{/code}}
178 {{/version}}
179
180 = Build and run =
181
182 {{code language="bash"}}
183 # Build
184 pnpm exec vite build
185 # Run
186 pnpm exec vite preview
187 # Start the XWiki instance
188 # Access Cristal at http://localhost:4173/ (or the URL displayed by the preview command)
189 {{/code}}
France 2030 Logo

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

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

  • Powered by XWiki 17.10.9-node2. Hosted and managed by XWiki SAS

Get Connected