Building (brisa build)
brisa build creates an optimized production build of your application. The output displays information about each route:
[ info ] Route | JS server | JS client (gz)
[ info ] ---------------------------------------------------------------
[ info ] ฮป /pages/index | 41 kB | 12 kB
[ info ] ฮป /pages/about-us | 1 kB | 7 kB
[ info ] ฮป /pages/user/[username] | 244 B | 2 kB
[ info ] ฮป /api/user/[username] | 105 B |
[ info ] ฦ /middleware | 401 B |
[ info ] ฮ /layout/index | 759 B |
[ info ] ฮฉ /i18n | 737 B |
[ info ] ฮจ /websocket | 8 B |
[ info ] ฮ /web-components/_integrations | 528 B |
[ info ]
[ info ] ฮป Server entry-points
[ info ] ฮ Layout
[ info ] ฦ Middleware
[ info ] ฮฉ i18n
[ info ] ฮจ Websocket
[ info ] ฮ Web components integrations
[ info ] - client code already included in each page
[ info ] - server code is used for SSR
[ info ]
[ info ] ฮฆ JS shared by all
[ info ]
[ info ] โ Compiled successfully!
[ info ] โจ Done in 253.72ms.
- JS server: The number of bytes of JavaScript code that will be executed on the server.
- JS client (gz): The number of bytes of JavaScript code that will be sent to the client, after being compressed with gzip.
Only the JS client code is compressed with gzip. The JS server code size is without compression.
To get a list of the available options with brisa build, run the following command inside your project directory:
brisa build --help
The output should look like this:
Usage: brisa build [options]
Options:
-d, --dev Build for development (useful for custom server)
-w, --web-component Build standalone web component to create a library
-c, --component Build standalone server component to create a library
-s, --skip-tauri Skip open tauri app when 'output': 'desktop' | 'android' | 'ios' in brisa.config.ts
--help Show help
Build different outputs
If you want to build your application for different outputs, you can use the output field in the brisa.config.ts file. The available outputs are:
- server: The default output. It generates a server-side application.
- static: Generates a static application.
- desktop: Generates a desktop application.
- android: Generates an Android application.
- ios: Generates an iOS application.
If you want to make a desktop app for Windows, another one for Mac, also android and ios, all at the same time. We recommend you do this in an array inside a pipeline and use an environment variable to decide the output.
The good thing is that if you are on Windows, it will use the native Windows stuff for the Desktop app build, the same with Linux and Mac.
Development build
brisa build -d creates a development build of your application. This build is useful for custom servers.
Web component build
Brisa is more than a framework; it is a Web Component Compiler. You can create web components using Brisa and build them to create a library.
brisa build -w path/web-component.tsx creates a standalone web component to create a library. The path to the file can be relative or absolute. The output will be:
The name of the web component is going to be the name of the file. For example, if your file is
custom-counter.tsx, the name of the web component will becustom-counter.
The output will be:
[ wait ] ๐ building your standalone components...
[ info ]
[ info ] Standalone components:
[ info ] - build/custom-counter.server.js (646.00 B)
[ info ] - build/custom-counter.client.js (425.00 B)
[ info ]
[ info ] โจ Done in 59.78ms.
In the case that you need to build more than one web component, you can use the --web-component flag multiple times:
brisa build -w path/web-component1.tsx -w path/web-component2.tsx
After running the command, you will have a web-component1.client.js, web-component1.server.ts, web-component2.client.js, and web-component2.server.ts file.
[ wait ] ๐ building your standalone components...
[ info ]
[ info ] Standalone components:
[ info ] - build/web-component1.server.js (646.00 B)
[ info ] - build/web-component1.client.js (425.00 B)
[ info ] - build/web-component2.server.js (646.00 B)
[ info ] - build/web-component2.client.js (425.00 B)
[ info ]
[ info ] โจ Done in 153.72ms.
Why theses files?
- *.client.js: The client-side code of the web component.
- *.server.ts: The server-side code of the web component, used for SSR.
Even though it is called "server", it does not mean that it is a "server component", it is still a "web component", which is transformed to be able to do SSR of it, taking into account the Declarative Shadow DOM and the access to the WebContext.
Client-side code usage
Example using these web components in Vanilla JavaScript:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Example</title>
<script type="importmap">
{
"imports": {
"brisa/client": "https://unpkg.com/brisa@latest/client-simplified/index.js"
}
}
</script>
<script type="module" src="web-component1.client.js"></script>
<script type="module" src="web-component2.client.js"></script>
</head>
<body>
<web-component1></web-component1>
<web-component2></web-component2>
</body>
</html>
The import map is necessary outside of the Brisa framework to map
brisa/clienttobrisa/client-simplified. This is because the Brisa client is internally used by the Brisa framework and we did a simplified version to be used outside of the framework.
SSR of Web Component
Example server-side rendering these web components in a different JSX framework:
import { renderToString } from 'brisa/server';
import WebComponent1 from './web-component1.server.ts';
import WebComponent2 from './web-component1.server.ts';
const htmlWC1 = await renderToString(<WebComponent1 foo="bar" />);
const htmlWC2 = await renderToString(<WebComponent2 foo="bar" />);
In the case of incompatibilities with the jsx-runtime, you can use the jsx function:
import { renderToString } from 'brisa/server';
import { jsx } from 'brisa/jsx-runtime';
import WebComponent1 from './web-component1.server.ts';
import WebComponent2 from './web-component1.server.ts';
const htmlWC1 = await renderToString(jsx(WebComponent1, { foo: "bar" }));
const htmlWC2 = await renderToString(jsx(WebComponent2, { foo: "bar" }));
The Web Components during SSR are transformed into Declarative Shadow DOM.
Component build
brisa build -c path/component.ts creates a standalone server component to create a library. The path to the file can be relative or absolute. The output will be:
[ wait ] ๐ building your standalone components...
[ info ]
[ info ] Standalone components:
[ info ] - build/component.server.js (446.00 B)
[ info ]
[ info ] โจ Done in 53.71ms.
In the case that you need to build more than one component, you can use the --component flag multiple times:
brisa build -c path/component1.ts -c path/component2.ts
After running the command, you will have a component1.server.ts and a component2.server.ts file.
[ wait ] ๐ building your standalone components...
[ info ]
[ info ] Standalone components:
[ info ] - build/component1.server.js (446.00 B)
[ info ] - build/component2.server.js (426.00 B)
[ info ]
[ info ] โจ Done in 72.31ms.
How to use the server component
Example using this server component in a different framework:
import { renderToString } from 'brisa/server';
import { Component } from 'path/component.server.ts';
const html = await renderToString(<Component foo="bar" />);
In the case of incompatibilities with the jsx-runtime, you can use the jsx function:
import { renderToString } from 'brisa/server';
import { jsx } from 'brisa/jsx-runtime';
const html = await renderToString(jsx(Component, { foo: 'bar' }));
Server Actions are not supported in standalone components for security reasons.
Skip open Tauri app
When the output is set to desktop, ios, or android in brisa.config.ts, the build is done twice:
- The first build is for the statics files.
- The second build is for the desktop, ios, or android app (Integration with Tauri).
brisa build -s skips the integration with Tauri and only builds the static files.
Learn more about the app strategy (
server,static,desktop,android,ios) here.