Overview

CLI tool

SDKs

Project setup and initialization

Auth Overview

Email account

Identity Providers

Anonymous account

Firestore

Collection

Document

Query

Create and update data

Firestore timestamps

Firestore Security rules

Storage

File references and metadata

List files and folders

Read, download files

Upload data

Setting the bucket CORS header

Cloud Functions

Define Callable functions

Invoke Callable functions

HTTP functions

Functions on Auth events

Functions on Firestore events

JS Dates and Callable Functions

Environment variables

Debug Functions locally

Schedule execution: Cron jobs

GenKit

.prompt Prompt file

TypeScript Prompt file

# Overview

<div class="bookHeroImage" style="padding: 32px;margin: 8px 0;">
<svg viewBox="0 0 749 205" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M707.39 161.434C700.156 161.434 693.615 159.749 687.768 156.379C682.021 153.01 677.512 148.352 674.241 142.406C670.971 136.361 669.336 129.623 669.336 122.19C669.336 115.055 670.872 108.514 673.944 102.568C677.115 96.5234 681.525 91.7666 687.174 88.2981C692.822 84.7306 699.264 82.9468 706.498 82.9468C713.931 82.9468 720.372 84.5819 725.823 87.8522C731.372 91.1225 735.584 95.6811 738.458 101.528C741.332 107.276 742.769 113.915 742.769 121.447C742.769 122.339 742.719 123.231 742.62 124.123C742.521 125.014 742.471 125.51 742.471 125.609H685.687C686.183 132.348 688.611 137.551 692.971 141.217C697.332 144.884 702.286 146.717 707.836 146.717C716.359 146.717 722.899 142.753 727.458 134.825L741.431 141.515C738.16 147.56 733.602 152.415 727.755 156.082C722.007 159.65 715.219 161.434 707.39 161.434ZM726.12 113.123C725.922 110.744 725.129 108.316 723.742 105.839C722.354 103.361 720.174 101.28 717.201 99.5955C714.327 97.8117 710.71 96.9198 706.35 96.9198C701.494 96.9198 697.282 98.4063 693.714 101.379C690.246 104.352 687.868 108.267 686.579 113.123H726.12Z" fill="#5E5E5E"/>
<path d="M633.449 161.434C625.025 161.434 618.039 159.501 612.489 155.636C607.039 151.672 603.174 146.717 600.895 140.771L615.462 134.528C617.147 138.591 619.575 141.663 622.746 143.744C626.016 145.825 629.584 146.866 633.449 146.866C637.512 146.866 640.832 146.123 643.408 144.636C645.985 143.051 647.273 141.019 647.273 138.542C647.273 136.163 646.233 134.231 644.151 132.744C642.07 131.159 638.651 129.771 633.895 128.582L623.786 126.204C618.237 124.915 613.431 122.537 609.368 119.069C605.404 115.501 603.422 110.893 603.422 105.244C603.422 98.4063 606.246 93.0054 611.895 89.0414C617.543 84.9783 624.48 82.9468 632.705 82.9468C639.543 82.9468 645.588 84.3837 650.841 87.2576C656.192 90.1315 660.057 94.2937 662.435 99.7441L648.016 105.839C646.629 102.767 644.498 100.487 641.624 99.0009C638.75 97.5144 635.629 96.7711 632.26 96.7711C628.989 96.7711 626.115 97.5144 623.638 99.0009C621.16 100.388 619.922 102.271 619.922 104.65C619.922 106.731 620.764 108.415 622.449 109.704C624.232 110.992 627.007 112.082 630.773 112.974L641.773 115.65C649.205 117.532 654.755 120.406 658.422 124.271C662.088 128.037 663.922 132.596 663.922 137.947C663.922 142.307 662.584 146.271 659.908 149.839C657.332 153.406 653.715 156.231 649.057 158.312C644.498 160.393 639.296 161.434 633.449 161.434Z" fill="#5E5E5E"/>
<path d="M555.223 161.434C549.971 161.434 545.214 160.393 540.953 158.312C536.791 156.132 533.471 153.159 530.993 149.393C528.615 145.528 527.426 141.168 527.426 136.312C527.426 128.582 530.3 122.487 536.047 118.028C541.894 113.568 549.277 111.339 558.196 111.339C566.025 111.339 572.714 112.677 578.264 115.352V112.231C578.264 107.771 576.48 104.105 572.912 101.231C569.444 98.2576 565.232 96.7711 560.277 96.7711C552.746 96.7711 546.701 99.8432 542.142 105.987L529.656 97.3657C533.124 92.7081 537.435 89.1405 542.588 86.663C547.84 84.1855 553.737 82.9468 560.277 82.9468C571.079 82.9468 579.403 85.672 585.25 91.1225C591.196 96.4738 594.169 104.055 594.169 113.866V159.055H578.264V149.988H577.372C574.994 153.357 571.971 156.132 568.304 158.312C564.638 160.393 560.277 161.434 555.223 161.434ZM557.899 147.906C561.566 147.906 564.935 147.015 568.007 145.231C571.178 143.348 573.656 140.92 575.439 137.947C577.322 134.875 578.264 131.605 578.264 128.136C573.012 125.262 567.412 123.825 561.466 123.825C556.016 123.825 551.755 125.014 548.683 127.393C545.611 129.771 544.075 132.794 544.075 136.46C544.075 139.83 545.412 142.605 548.088 144.785C550.863 146.866 554.133 147.906 557.899 147.906Z" fill="#5E5E5E"/>
<path d="M486.618 161.433C481.266 161.433 476.46 160.294 472.199 158.014C468.037 155.735 464.915 152.861 462.834 149.393H461.942V159.055H446.482V52.6221H462.834V84.5816L461.942 94.8384H462.834C464.915 91.469 468.037 88.6447 472.199 86.3654C476.46 84.0861 481.266 82.9465 486.618 82.9465C492.96 82.9465 498.807 84.6312 504.158 88.0006C509.609 91.3699 513.92 96.0772 517.091 102.122C520.361 108.068 521.996 114.757 521.996 122.19C521.996 129.622 520.361 136.312 517.091 142.257C513.92 148.203 509.609 152.911 504.158 156.379C498.807 159.749 492.96 161.433 486.618 161.433ZM483.793 146.42C487.658 146.42 491.226 145.429 494.496 143.447C497.865 141.465 500.541 138.64 502.523 134.974C504.604 131.208 505.645 126.947 505.645 122.19C505.645 117.433 504.604 113.221 502.523 109.555C500.541 105.789 497.865 102.915 494.496 100.933C491.226 98.951 487.658 97.9601 483.793 97.9601C479.928 97.9601 476.311 98.951 472.942 100.933C469.672 102.915 466.996 105.739 464.915 109.406C462.933 113.073 461.942 117.334 461.942 122.19C461.942 127.046 462.933 131.307 464.915 134.974C466.996 138.64 469.672 141.465 472.942 143.447C476.311 145.429 479.928 146.42 483.793 146.42Z" fill="#5E5E5E"/>
<path d="M401.365 161.434C394.13 161.434 387.59 159.749 381.743 156.379C375.995 153.01 371.486 148.352 368.216 142.406C364.946 136.361 363.311 129.623 363.311 122.19C363.311 115.055 364.847 108.514 367.919 102.568C371.09 96.5234 375.5 91.7666 381.148 88.2981C386.797 84.7306 393.239 82.9468 400.473 82.9468C407.905 82.9468 414.347 84.5819 419.797 87.8522C425.347 91.1225 429.559 95.6811 432.432 101.528C435.306 107.276 436.743 113.915 436.743 121.447C436.743 122.339 436.694 123.231 436.595 124.123C436.495 125.014 436.446 125.51 436.446 125.609H379.662C380.157 132.348 382.585 137.551 386.946 141.217C391.306 144.884 396.261 146.717 401.811 146.717C410.333 146.717 416.874 142.753 421.432 134.825L435.405 141.515C432.135 147.56 427.577 152.415 421.73 156.082C415.982 159.65 409.194 161.434 401.365 161.434ZM420.095 113.123C419.896 110.744 419.104 108.316 417.716 105.839C416.329 103.361 414.149 101.28 411.176 99.5955C408.302 97.8117 404.685 96.9198 400.324 96.9198C395.468 96.9198 391.257 98.4063 387.689 101.379C384.221 104.352 381.842 108.267 380.554 113.123H420.095Z" fill="#5E5E5E"/>
<path d="M317.93 85.3252H333.389V96.3252H334.281C335.867 92.5595 338.741 89.4378 342.903 86.9603C347.065 84.3838 351.326 83.0955 355.687 83.0955C359.254 83.0955 362.178 83.591 364.457 84.582V101.677C361.087 99.9919 357.322 99.1496 353.16 99.1496C347.808 99.1496 343.299 101.231 339.632 105.393C336.065 109.456 334.281 114.46 334.281 120.406V159.055H317.93V85.3252Z" fill="#5E5E5E"/>
<path d="M294.594 72.8384C291.522 72.8384 288.896 71.7979 286.715 69.7168C284.634 67.5366 283.594 64.9105 283.594 61.8384C283.594 58.7663 284.634 56.1897 286.715 54.1087C288.896 51.9285 291.522 50.8384 294.594 50.8384C297.666 50.8384 300.242 51.9285 302.324 54.1087C304.504 56.1897 305.594 58.7663 305.594 61.8384C305.594 64.9105 304.504 67.5366 302.324 69.7168C300.242 71.7979 297.666 72.8384 294.594 72.8384ZM286.418 85.325H302.769V159.055H286.418V85.325Z" fill="#5E5E5E"/>
<path d="M211.938 52.6221H276.6V68.5275H228.586V99.1492H271.843V114.906H228.586V159.055H211.938V52.6221Z" fill="#5E5E5E"/>
<path d="M51.2275 191.109C59.4031 194.399 68.2727 196.352 77.5857 196.677C90.1896 197.117 102.175 194.511 112.89 189.561C100.041 184.513 88.4043 177.131 78.4729 167.952C72.0352 178.26 62.5135 186.401 51.2275 191.109Z" fill="#FF9100"/>
<path d="M78.4711 167.955C55.8006 146.988 42.0477 116.641 43.21 83.3558C43.2478 82.2749 43.3048 81.1947 43.3715 80.1148C39.3113 79.0647 35.0725 78.4239 30.7103 78.2716C24.4663 78.0535 18.4195 78.8279 12.7108 80.4355C6.659 91.0365 3.00696 103.2 2.552 116.228C1.37785 149.852 21.7254 179.231 51.2257 191.112C62.5117 186.404 72.0331 178.272 78.4711 167.955Z" fill="#FFC400"/>
<path d="M78.472 167.954C83.7428 159.519 86.9386 149.63 87.3106 138.976C88.2893 110.95 69.4486 86.8412 43.3725 80.1137C43.3058 81.1936 43.2487 82.2738 43.211 83.3547C42.0486 116.64 55.8015 146.987 78.472 167.954Z" fill="#FF9100"/>
<path d="M84.3945 1.33524C69.5432 13.233 57.8158 28.9212 50.7205 46.9936C46.6583 57.3453 44.1056 68.4647 43.3603 80.1206C69.4365 86.8481 88.2772 110.957 87.2985 138.983C86.9264 149.637 83.7213 159.516 78.4599 167.961C88.391 177.149 100.028 184.522 112.877 189.57C138.667 177.649 156.965 151.996 158.025 121.654C158.711 101.995 151.158 84.4744 140.485 69.6852C129.214 54.0442 84.3945 1.33524 84.3945 1.33524Z" fill="#DD2C00"/>
</svg></div>

Firebase allows developers to create a fully featured backend on top of servers and APIs operated by Google.

### overall benefits

-   solid developer experience
-   it may scale to world-scale use
-   reasonable free-tier and pay-as-you-go model
-   high quality docs, well supported by AI models
-   actively developed and maintained

### main backend components covered in this document

-   authentication with Firebase Auth
-   database with Cloud Firestore
-   storage with Cloud Storage
-   serverless functions with Cloud Functions

### focus of this document: web-centric

We focus on creating a backend for web-apps, and use the web-centric client SDKs. We use TypeScript where possible, and pick Node.js as the runtime for Cloud Functions.



# CLI tool

The Firebase CLI tool enables several workflows:

-   we emulate the Firebase backend locally, to run it and debug it at no cost: authentication, databases, storage and serverless functions.
-   It is the only tool to set up the Cloud Functions' directory, and deploy them.
-   we provide secrets to Google, and manage them. We register and deploy security rules.
-   we list the Firebase projects linked to the Google account.

### the CLI executable

The _firebase_ CLI executable is provided by the _firebase-tools_ npm package.

```bash
npm install -g firebase-tools
firebase
```

[Release notes](https://github.com/firebase/firebase-tools/releases)

### Google account

Firebase projects are scoped to a Google account.

```bash
firebase login
firebase login:list # prints current Google account
firebase logout
```

### list projects and select one

```bash
firebase projects:list
firebase use imagetales
```

### project configuration and scaffolding

The _init_ command enables several workflows:

-   scaffold the Cloud Functions directory
-   set up and configure the emulators
-   add security rules for Firestore and Cloud Storage
-   set up Firebase Hosting to deploy static web apps

```bash
firebase init
```

### help

The general help prints all commands. We may also target specific commands.

```bash
firebase help
firebase help | grep functions
firebase help | grep firestore

firebase help emulators:start
firebase help deploy
```

### cloud functions and secrets

```bash
firebase init
firebase functions:list

firebase functions:shell

firebase functions:secrets:access ABC_API_KEY
firebase functions:secrets:set ABC_API_KEY
firebase functions:secrets:destroy ABC_API_KEY

firebase deploy --only functions
firebase deploy --only functions:requestPlanet
```

### emulators

```bash
firebase emulators:start
firebase emulators:start --import emulator-data --export-on-exit
```

We specify which emulators to run in `firebase.json`. We may provide the port, or an empty object to use the default port. We may scaffold this file with _firebase init_.

```json
{
    "emulators": {
        "firestore": { "port": 8080 },
        "auth": { "port": 9099 },
        "functions": { "port": 5001 },
        "storage": { "port": 9199 },
        "ui": { "enabled": true }
    },
    "storage": { "rules": "storage.rules" },
    "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json"
    },
    "functions": [
        /* ... */
    ]
}
```

### security rules and rule deployment

The storage emulator requires storage access rules. We define Storage rules in _storage.rules_. We define Firestore rules in _firestore.rules_

```bash
firebase deploy --only storage
firebase deploy --only firestore:rules
```

### _gcloud_: Google Cloud CLI tool

_gcloud_ enables some operations not available in the _firebase_ tool, such as listing secrets of a given project or describing a Storage bucket.

Note: we install _gcloud_ from [an archive provided by Google](https://docs.cloud.google.com/sdk/docs/install-sdk), not from the deprecated npm package.

```
gcloud secrets list --project <PROJECT_ID>
gcloud storage buckets describe gs://abcd.firebasestorage.app
```



# SDKs

We interact with the backend with the help of SDKs.

### client SDKs

The client SDKs run on unprivileged clients, such as in browsers. The JavaScript SDK is designed to run on browsers but may also run on Node.js apps that want to act as (unprivileged) clients.

    npm i firebase

-   [JavaScript client SDK - Release notes](https://firebase.google.com/support/release-notes/js)

### admin SDK: privileged environments

The admin SDK is designed to perform sensitive operations from secure, privileged environments.

The admin SDK authenticates itself against Google servers by using a privileged account called a _service account_. _Service accounts_ are automatically created by Google, are scoped to a Firebase project and have specific entitlements. The admin SDK skips user-centric authentication and bypass client-centric security rules.

We notably use the admin SDK within Cloud Functions, which run on Google servers. Google pre-configures the environment with a _service account_, which the admin SDK detects and uses. As such, we don't have to configure the admin SDK ourselves.

We may use the Node.js admin SDK:

    npm i firebase-admin

-   [Node.js admin SDK - Release notes](https://firebase.google.com/support/release-notes/admin/node/)
-   [Node.js admin SDK - Reference](https://firebase.google.com/docs/reference/admin/node/firebase-admin)

Note: The admin and client SDK expose similar APIs in some areas.

### Cloud Functions SDK

We use a Cloud Functions SDK to define Cloud Functions.

We may use the _Node.js_ Cloud Functions SDK.

When we scaffold the Cloud Functions directory with _firebase init_, it adds the SDK as a dependency.

```json
"firebase-functions": "^7.0.0",
```



# Project setup and initialization

### Identify the Firebase project (client SDK)

The config object stores credentials to identify the Firebase project when interacting with Google servers. These credentials are not sensitive or confidential _per se_ since they only serve to identify the project. They are exposed on the client.

```ts
const firebaseConfig = {
    apiKey: "....",
    authDomain: ".....firebaseapp.com",
    projectId: "....",
    storageBucket: ".....firebasestorage.app",
    messagingSenderId: "....",
    appId: "....",
}
```

### initialize the app and embed the configuration in a helper object

We initialize a client SDK with a given config. It returns a helper object that we initialize other services with.

```ts
const app = initializeApp(firebaseConfig)
```

When working with several Firebase projects, we initialize client SDKs with different configs. Additional client SDKs require an internal string identifier that may be any string. The first client has a _"[DEFAULT]"_ internal string identifier.

```ts
const app1 = initializeApp(firebaseConfig1)
const app2 = initializeApp(firebaseConfig2, "two")
```

### initialize the admin SDK

In Cloud Functions, the admin SDK is automatically configured. We get the _app_ helper with no config:

```ts
const app = initializeApp()
```



# Auth Overview



### authenticate app users

The client-SDK provides authentication flows to authenticate users against Firebase's authentication servers.

### the _auth_ helper and _currentUser_

We keep a reference to the _auth_ helper to use it in various functions. It also exposes `currentUser`.

```ts
const auth = getAuth(app)
auth.currentUser // User | null
```

_currentUser_ starts as _null_. When the SDK has finished loading and the user is logged-in, _currentUser_ switches to a _User_ instance.

_currentUser_ holds _uid_, the user unique identifier. The other properties may be empty:

```ts
currentUser.uid
currentUser.email
currentUser.phoneNumber
currentUser.displayName
currentUser.isAnonymous
```

### main pattern: react to authentication state changes

We provide a callback to _onAuthStateChanged_, which Firebase runs on auth events. Firebase gives us a _user_ object, also of type _User_, and which is _null_ when there is no authenticated user.

```ts
onAuthStateChanged(auth, (user) => {
    if (user) {
        // user.uid
    }
})
```

The auth events are as follows:

-   the auth SDK has finished loading and no user is authenticated
-   the user registers (sign up)

-   the user logs in (sign in)
-   the user logs out (sign out)

The login occurs in three scenarios:

-   the user is recognized by the SDK and is logged in automatically (credentials stored in browser)
-   the user fills the standard login form or logs in through an identity provider (hard-login)
-   the user is automatically logged-in after a successful sign-up. Note: a single authentication event occurs.

### _React_ patterns

We make the authentication status part of the _React_ state. For example, we work with a _isSignedIn_ variable. We make the display of the authenticated area conditional on _isSignedIn_ being true.

On page load, the Auth SDK is loading: _user_ starts as _null_. Once the SDK is loaded, _user_ may switch to a User instance, in a quick UI flicker.

As a best practice, we wait for the SDK load before showing some UI: we track the loading state in a one-off state variable that switches to _true_ on the first authentication event:

```tsx
const [hasLoaded, setHasLoaded] = useState(false)
const [isSignedIn, setisSignedIn] = useState(false)

useEffect(() => {
    const unsub = onAuthStateChanged(auth, (user) => {
        setHasLoaded(true)
        setisSignedIn(Boolean(user))
    })
    return unsub
}, []) // subscribe once, subscribe automatically.

if (!hasLoaded) return null
if (!isSignedIn) return <Lobby />
return <Ingame />
```

### sign out

sign out is consistent across all authentication flows:

```ts
signOut(auth)
```

# Email account



### registration

We collect the user's email and password:

```ts
createUserWithEmailAndPassword(auth, email, password)
    .then((credential) => { /* credential.user.uid */ }
    .catch((error) => {/* */})
    .finally(() => {/* */})
```

### hard-login

We collect the user's email and password:

```ts
signInWithEmailAndPassword(auth, email, password)
```

### password reset

Firebase sends a password-reset email to the provided email. We may customize the mail content on the Firebase console:

```ts
sendPasswordResetEmail(auth, email)
```

### email provider data (implementation detail)

The email provider's ID is _password_. The email provider data is added to _providerData_:

```json
{
    "providerData": [
        {
            "providerId": "password",
            "uid": "user@example.com",
            "email": "user@example.com",
            "displayName": null,
            "phoneNumber": null,
            "photoURL": null
        }
    ]
}
```

###

# Identity Providers



## Google Provider

Note: We must first enable the Google provider in the Firebase console.

```ts
const provider = new GoogleAuthProvider()
```

### popup flow: "continue with Google"

The popup authentication flow supports both sign-in and sign-up. Google detects returning users. We may name the button _"Continue with Google"_.

```ts
const result = await signInWithPopup(auth, provider)
```

Note: We may detect that it is a new user. For example, we display a welcome toast. We should not trigger important actions since there is no retry if it fails.

```ts
const info = getAdditionalUserInfo(result)
if (info?.isNewUser) {
    /**/
}
```

### redirect flow

The redirect flow relies on navigating to another page and navigating back. It isn't subject to popup prevention that may apply to the popup flow.

It requires extra work unless the website is hosted on Firebase Hosting.

# Anonymous account



We register an anonymous account with no action or data from the user. The account credentials are stored in the browser: the user may not access the account from other devices, and may not recover the account if the credentials are deleted.

Registration of anonymous accounts doesn't trigger the _beforeUserCreated()_ blocking function but it does trigger the _auth.user().onCreate_() non-blocking function.

```ts
signInAnonymously(auth)
```

### check if the account is anonymous

On the client, we check _currentUser_:

```ts
auth.currentUser?.isAnonymous // is true for anonymous accounts
```

In Cloud Functions' auth-related functions such as _user().onCreate()_, we access a _UserRecord_ user and check the _providerData_ array. If it's empty, it is an anonymous account:

```ts
user.providerData.length === 0 // is true for anonymous accounts
```

### convert to an email account

We link the anonymous account to an email credential that we build manually.

```ts
const credential = EmailAuthProvider.credential(email, password)
linkWithCredential(auth.currentUser, credential)
```

### link with a Provider such as a Google account

We link the anonymous accounts to an identity provider. For example, we link to a Google account with a popup flow.

```ts
const provider = new GoogleAuthProvider()
const result = await linkWithPopup(auth.currentUser!, provider)
```

# Firestore



### conceptual

Firestore is a NoSQL database that is most similar to MongoDB. It's made of collections and documents.

A _collection_ is a set of documents.

A _document_ is a set of fields. A document may contain 20k fields and 1 MiB of data.

A _reference_ serves to identify a collection or a document in the database. It doesn't guarantee the collection or document existence: It's merely a path that may point to nothing.

### references

-   [client SDK (JavaScript)](https://firebase.google.com/docs/reference/js/firestore_.md#@firebase/firestore)
-   [admin SDK (Node.js)](https://firebase.google.com/docs/reference/admin/node/firebase-admin.firestore)
-   [@google-cloud/firestore (Node.js)](https://docs.cloud.google.com/nodejs/docs/reference/firestore/latest/)

### packages and import paths

_firebase-admin_ is a wrapper around _[@google-cloud/firestore](https://docs.cloud.google.com/nodejs/docs/reference/firestore/latest)_. It has the same syntax and capabilities.

```ts
"firebase/firestore" // client SDK
"firebase/firestore/lite" // client SDK

"firebase-admin/firestore" // admin SDK
```

### init and db helper object

We init a _db_ object with the config, for use in Firestore-related functions.

```ts
const db = getFirestore(app)
```

# Collection



## Collection Reference

### collection reference usage

We provide the collection reference to:

-   fetch all documents - `getDocs(colRef)`

-   build a query targeting the collection - `query(colRef, filters..)`

-   build a random ID document reference - `doc(colRef)`, or one that refers to a specific document - `doc(colRef, docId)`
-   add a document to the collection, with a random ID generated on the fly - `addDoc(colRef, data)`.

### build a collection reference

We use the collection path to identify it uniquely. There is no slash prefix for root collections. Root collections have a simple path, such as `"users"`. Subcollections have a path made from several components.

We provide the path as:

-   a single string with slash separators.

-   a sequence of strings, with no slash separators.

```ts
const collectionRef = collection(db, "users")
const collectionRef = collection(db, `users/${uid}/custom_list`)
const collectionRef = collection(db, "users", uid, "custom_list")
```

```ts
// firebase-admin/firestore
const collectionRef = db.collection("users")
const collectionRef = db.collection(`users/${uid}/custom_list`)
```

### TypeScript: set the document's type at the collection level.

Collections are schema-less: they don't define the shape of their documents. The SDK cannot guess the document's data nor its type, and it doesn't validate data.

When receiving documents from the database, the client SDK checks the actual content and instantiates document objects with it, with no regard to hypothetical schemas or data validation. Instead, the document objects may be of any shape and be different from one another.

The SDK uses an abstract _DocumentData_ type to fit all kind of document shapes and content.

We may provide a more precise document type at the collection reference level. Since there is no check the data fits the more precise type, it is a type assertion. Yet, it is still more useful than relying on the abstract _DocumentData_ type.

```ts
const colRef = collection(db, "players") as CollectionReference<Player, Player>
// CollectionReference<AppModelType, DbModelType>
```

The SDK technically supports two document types, but in our scenario, we do not distinguish, so we provide the same type twice.

## Converter

_DbModel_ represents the shape instantiated by the SDK when receiving (conforming) data.

We use a converter when we don't want to use _DbModel_ within the app. We transform it to a shape to use within the app, that we call _AppModel_. Before sending to Firestore, we convert back to _DbModel_.

Transformation examples:

-   _DbModel_ has a Timestamp field but we prefer working with a Date field.
-   We add client-only properties to _AppModel_, such as helpers.

### implement the converter

We transform the documents at the app boundaries:

-   upon receiving from Firestore (`fromFirestore()`)
-   upon preparing to send to Firestore (`toFirestore()`)

We define two functions and add them to the converter.

_fromFirestore()_ takes the snapshot as received (_DocumentSnapshot_):

```ts
fromFirestore(snapshot: QueryDocumentSnapshot<FirestoreWorkout>): Workout{
		// to client shape
		const firestoreWorkout = snapshot.data()
		const workout = { ...firestoreItem, date: firestoreItem.date.toDate()}
     return workout
    }
```

_toFirestore()_ takes the object in its app-side shape.

```ts
toFirestore(workout: Workout) {
		// to database shape
        	return { ...workout, date: Timestamp.fromDate(workout.date)}
    }
```

We gather the transforms in the converter (_FirestoreDataConverter_). While the type may be inferred from the transforms, we may still add them for safety.

```ts
// FirestoreDataConverter<AppModel, DbModel>
const myConverter: FirestoreDataConverter<Workout, FirestoreWorkout> = {
    toFirestore() {},
    fromFirestore() {},
}
```

We attach it to the collection reference to let it type its documents.

```ts
const colRef = collection(db, "players").withConverter(conv)
```

# Document



## Document reference

The document reference identifies a document within the database, and embeds meta information.

We may find: the parent collection's reference, the document's id and the document's path as a string.

```ts
docRef.parent
docRef.id
docRef.path
```

### use document reference: CRUD operations

We provide the document reference for CRUD operations:

-   create the document, or override an existing one (upsert) - `setDoc(ref, data)`

-   update an existing document (it errors if the document isn't found) - `updateDoc(ref, data)`

-   read the document - `getDoc(ref)`

-   delete the document - `deleteDoc(ref)`

### build a document reference

The document's path identifies it uniquely. We provide the path as a single string or build it from string components.

```ts
const docRef = doc(db, "users", id) // string components
const docRef = doc(db, "users", "Nk....WQ")

const docRef = doc(db, "users/Nk....WQ") // single string
const docRef = doc(db, "users/" + id)

const docRef = collectionRef.doc("John") // admin sdk
const docRef = collectionRef.doc("NkJz11WQ")
```

We may alternatively provide the collectionRef and the document ID. If we want Firestore to generate the document ID on our behalf, we omit the ID. We receive the document's reference.

```ts
const docRef = doc(collectionRef, id)
const docRef = doc(collectionRef) // ID is generated by firestore
```

### read document at reference

Since it's okay for the reference to point to a non-existing document, the read operation does not error if no document id found. Instead, it is a valid way to detect if a document at this path exists or not. The read functions return a Document snapshot, which may be empty.

```ts
getDoc(docRef)
docRef.get() // db.collection("messages").doc(id).get()
```

## Document snapshot

The document snapshot is a wrapper that doesn't guarantee the document existence.

When we request a document, the SDK constructs a a wrapper (_DocumentSnapshot_) from the database's response. As a wrapper, it contains metadata and, if a document exists at this reference, it exposes the document too.

```ts
docSnapshot.exists()
docSnapshot.data() // undefined | DocumentData (or a more specific type)
```

```ts
docSnapshot.id // NkJz11WQ...7f
docSnapshot.ref // DocumentReference
docSnapshot.metadata // SnapshotMetadata
```

We may query a specific field:

```ts
docSnapshot.get("address.zipCode") // any
```

We may set up a subscription regarding a specific document reference to receive real-time snapshots on document change.

```ts
const unsub = onSnapshot(docRef, (docSnapshot) => {
    console.log("Current data: ", docSnapshot.data())
})
```

# Query



## overview

A query aims to target documents based on a set of criteria, instead of targeting documents through their reference.

### the result of a query: a query snapshot

Firestore answers a query with a query snapshot. It wraps a list of document snapshots. The list stays empty if there was no match.

The document snapshots are technically of type _QueryDocumentSnapshot_, but this type has the same API surface than _DocumentSnapshot_, so they are conceptually the same.

```ts
querySnaptshot.docs // list of document snapshots
querySnaptshot.empty
```

Document snapshots in the array are guaranteed to have an underlying document at `snapshot.data()` (_QueryDocumentSnapshot_ reflects that, removing _undefined_ from _data()_)

```ts
const cats = querySnapshot.docs.map((docSnapshot) => docSnapshot.data())
```

### a collection reference is technically a query

A collection ref is accepted as a query. In that case, we receive all documents:

```ts
getDocs(collectionRef)
collectionRef.get()
```

## build a query

### build a query

We query documents that match some criteria. We request a specific order and limit the document count.

```ts
const q = query(collectionRef, where(..), where(..), orderBy(..), limit(..))
const q = collection(..).where(..).orderBy(..).limit(..)
```

### where and where operators

We filter documents based on a property. We may request an exact value, or one within a range.

Note: documents that do not possess the property are filtered out.

```ts
where(propertyName, operator, value)
where("id", "==", user.id)
```

where operators (strings):

```ts
<
<=
>
>=
==
!=
array-contains // the array contains the specified value
array-contains-any // the array contains at least one of A, B or C ..
in // the property is equal to either A, B or C
not-in // the property is different from A, B and C.
```

### order documents based on a field

We order documents based on the value of a given field. By default, it sorts documents so that the value is ascending. It's best to be explicit about the ordering rather than rely on the default one.

```ts
orderBy(propertyName, orderDirection)
orderBy("postCount", "asc")
orderBy("postCount", "desc")
orderBy("postCount") // ascending
```

we can start from a given value, for example, documents that have at least 10 posts, or more than 10 posts:

```ts
startAt(10)
startAfter(10)
```

### limit the size of the query

get at most n documents

```ts
limit(n)
limit(5)
```

### pagination: start at or after a given document, that acts as a cursor

When doing pagination, we store the document snapshot we received last, and provide it in the new query.

```ts
startAfter(docSnapshot) // start after the docSnapshot
startAt(docSnapshot) // start at the docSnapshot (include it again)
```

## run the query

The client SDK's function name (_getDocs_) hints that we may receive several documents. The admin SDK is a get function from the query object.

```ts
getDocs(query)
query.get()
```

### real-time listener over the query

we provide a callback to handle the query snapshot.

```ts
const unsub = onSnapshot(query, (qs) => {
    const documents = qs.docs.map((docSnapshot) => docSnapshot.data())
    setMessages(documents)
})
```

# Create and update data



We assume we already constructed a document reference, or perform a reference-less document creation.

### document creation or override

We create or override document at docRef

    setDoc(docRef, data)
    docRef.set(data)

Reference-less document creation. By design a document won't exist there.

    addDoc(collectionRef, data)
    db.collection("message").add(data)

### document partial update

If we assume the document already exists, we should use the _update_ pattern, so that correctly fails if the document doesn't exist. Besides, TypeScript ensures we only update fields that are suppose to exist. The update pattern expects a _change_ object, with one or more fields to update. The other fields are left unchanged. We type the _change_ as a _Partial_ of the document, or we explicitely pick fields with a _Pick_ of the document.

```ts
updateDoc(docRef, data)
docRef.update(data)
```

### upset and updating data

we can technically update a document with a modified upsert that comes with the option to merge what exists and what we provide. Yet, this is still dangerous because if we omit the merge option, the document will be overridden by the change object:

```
setDoc(docRef, data, { merge: true })
docRef.set(data, { merge: true })
```

### delete document

```ts
docRef.delete()
deleteDoc(docRef)
```

### mutate a single field

we use the update() function along with a directive on a specific field.

### increment field

```ts
docRef.update({
    count: FieldValue.increment(),
})
```

### delete field

```ts
docRef.update({
    fleet: FieldValue.delete(),
})
```

### server timestamp for field

this creates a trusted timestamp object. this is not needed when doing
it from admin-sdk, because we may already trust a date created from the
admin environment. Besides, it uses firebase specific Timestamp instead
of a multi platform iso date string.

```ts
docRef.update({
    count: FieldValue.serverTimestamp(),
})
```

### Increment

```ts
const partialUserDoc = {
    activityScore: increment(1),
}
```

# Firestore timestamps



Storing dates as ISO _strings_ may be the best pattern as it is simple to reason about and it is portable across all systems and databases.

As the Firestore database comes with a [native value type for storing dates](https://firebase.google.com/docs/firestore/data-model) called _timestamp_, we describe using this pattern in this article. The Firestore SDK comes with a _Timestamp_ type that represents a _timestamp_ field.

### storing timestamps

As we attempt to store data, the SDK detects Date and Timestamp fields and assumes we want to store them as _timestamps_.

```ts
const user = {
    createdAt: new Date(),
    createdAt_: Timestamp.now(),
}
```

When preparing data to be transported through an HTTP request, the SDK serializes Date and Timestamp objects to objects with a single _timestampValue_ property.

```json
{
  "createdAt": { "timestampValue": "2025-10-07T18:47:13.279000000Z" },
  "createdAt_": { "timestampValue": "2025-10-07T18:47:13.279000000Z" }
},
```

The database detects this pattern and stores those field as _timestamps_.

### receiving timestamps

_Timestamp_ is the designed type to represent database _timestamps_. As we receive _timestamp_ fields from the database, the Firestore SDK instantiates them as _[Timestamp](https://firebase.google.com/docs/reference/node/firebase.firestore.Timestamp)_ objects.

# Firestore Security rules



We define the security rules in the Firebase console or in a _firestore.rules_ file. Firebase doesn't bill requests denied by security rules.

rules version

```ts
rules_version = "2"
```

### firestore scope

We start by scoping the rules to _cloud.firestore_

```ts
service cloud.firestore {
    // ...
    }
```

### database scope

We then scope the rules to the current database. This is boilerplate code: we don't use the _database_ wildcard variable.

```ts
match /databases/{database}/documents {
    // ...
}
```

### set rules for a given collection

We set rules for a given collection. The wildcard variable is the ID of the requested document. We may, for example, compare it with the user's authentication uid.

```ts
match /users/{user_id}{
    	// ...
}
```

### operations and condition

```ts
allow operation, operation: if condition;
```

operations

```ts
read
create
update
delete
```

### authentication, user ID

If the user is not authenticated, _request.auth_ is _null_. We may filter out unauthenticated users:

```
if request.auth != null;
```

The user's authentication _uid_ is available as _request.auth.uid_:

```ts
request.auth.uid
```

### green-light specific documents

We may-green light the document if its ID matches the user's _uid_.

```ts
    match /players/{player_id} {
         allow read: if request.auth.uid == player_id;
    }
```

Alternatively, we check if a field of the document matches the user's uid. For example, we check if the document's _owner_ field matches the user uid. _resource.data_ is the requested document.

```ts
    match /planets/{planet_id} {
         allow read: if request.auth.uid == resource.data.owner.id;
    }
```

Note: if auth is null, trying to read uid triggers a failsafe mechanism which denies the request. The same failsafe triggers if we attempt to read a field that doesn't exist on the requested resource.

### get authorization information in a separate document

We may read a different document with _get()_

```ts
get(/databases/$(database) / documents / users / $(request.auth.uid)).data.rank
```

This unlocks a pattern where we read some authorization data in a different document, such as the user document, which would store the user's entitlements or ranks. This may not be a good architecture.

For example, to require a specific rank:

```ts
    match /characters/{character_id} {
         allow update: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.rank == "Game Master";
    }
```

For example, to enforce that the requested character's zone is the same as the player's character's zone

    match /overworld_characters/{overworld_character} {
         allow read: if get(/databases/$(database)/documents/characters/$(request.auth.uid)).data.zone == resource.data.zone;
    }

check requested document

    resource.data.uid
    resource.data.zone
    resource.data.required_rank

### data validation

The request's payload is exposed as `request.resource`. We may check if one of its field has the expected value.

    request.resource.data.uid;
    request.resource.data.age > 0
      // A) user sends a post that mentions himself as uid
      allow create : if request.auth.uid == request.resource.data.uid;
    
      // B) user modifies a post that mentions himself as uid
      // A) he must send a post that still mentions him as uid
      allow update,delete: if
      request.auth.uid == resource.data.uid
      &&
      request.auth.uid == request.resource.data.uid;

# Storage



### reference

-   [client SDK - Storage](https://firebase.google.com/docs/reference/js/storage)

### object storage, file terminology and patterns

Firebase Storage is a wrapper around Google's [Cloud Storage](https://cloud.google.com/storage/?hl=en), a _cloud storage_ service.

It is technically an _object storage_ service because it stores immutable _objects_ in a flat _bucket_, instead of files in a hierarchical filesystem.

Firebase Storage reintroduces the concept of files, folders and file hierarchy, primarily through the convention of using paths as object names, such as `public/abc.png`. The SDKs and docs use the term _file_ instead of _objects_.

### project's default bucket (implementation detail)

A Firebase project is given a default bucket. The bucket's URI serves to distinguish it from other ones. It is made of two components: a `gs://` prefix and a domain name. The default bucket domain uses the project's name, which makes it globally unique. If we add another bucket, we must pick a globally unique name by ourselves:

```ts
"gs://<PROJECT-ID>.firebasestorage.app"
"gs://<PROJECT-ID>.appspot.com" // old default bucket URIs

"gs://<GLOBALLY-UNIQUE-ID>" // non-default bucket URI
```

Those are not HTTP URLs: no data is served if we force HTTP URLs out of them.

### initialization and storage helper

The client SDK initializes with the default bucket unless we specify another one. _storageService_ is a safer helper name since _storage_ is already exported by Firebase:

```ts
const storageService = getStorage(app)
const storageService = getStorage(app, "gs://...")
```

# File references and metadata



### file path

A file is uniquely identified by its path in the bucket: it is unambiguous ID. The path includes the file extension.

### file reference

We use references to interact with files. We build references by providing the file path:

```ts
const fileRef = ref(storage, "tts/2F14Izjv.mp3")
const fileRef = bucket.file("tts/2F14Izjv.mp3") // admin SDK
```

The file reference does not guarantee the file existence. The reference properties are of limited use (client SDK) and confusing:

```ts
ref.bucket // "abc.firebasestorage.app"
ref.fullPath // "tts/2F14Izjv.mp3"
ref.name // "2F14Izjv.mp3"

// computed references
ref.parent // ref(storage, "tts")
ref.root // ref(storage, "/")
```

### bucket file's metadata

We fetch an existing file's metadata:

```ts
const metadata = await getMetadata(fileRef) // client SDK
```

It is a _[FullMetadata](https://firebase.google.com/docs/reference/js/storage.fullmetadata)_ instance. We have:

-   the file size in bytes
-   the MIME type
-   the date of creation as an ISO string:

```ts
// repeat from fileRef
metadata.bucket
metadata.fullPath
metadata.name

// size, type and time
metadata.size // 1048576
metadata.contentType // "audio/mpeg"
metadata.timeCreated // "2026-01-04T12:34:56.789Z"

metadata.ref // file reference
```

# List files and folders



### folder and prefix terminology

The API describes folders as _prefixes_, but the docs also mention _folders_.

### folder existence

A file, by its name alone, may create several nested _folders_ because we read it as a path. For example, _abc/def/hello.pdf_ creates two folders: _abc_ and _def_. Those folders do not exist _per se_, but only because we follow this arbitrary convention.

In this convention, folders can't be empty: if there _is_ a folder, there _is_ a nested file.

### get references at folder level

We build a reference to a folder and list its content. The list API trims the nested items (shallow list).

The list discriminates files (_items_) from folders (_prefixes_), but both are exposed as references (StorageReference\_). The list exposes them as two arrays.

```ts
folderRef = ref(storage, "uploads")

const result = await list(directoryRef, { maxResults: 100 })
// const result = await listAll(directoryRef)

result.items // StorageReference[]
result.prefixes // StorageReference[]
```

# Read, download files



### general considerations

-   The client SDK enforces access-rules. Some functions allow the user to save a bearer URL which bypasses the security rules (one-off access control).
-   Download workflows are influenced by the browser requirements and restrictions.

### get a HTTP URL on the client

We may request a read URL. Access control is performed when requesting the URL.

The returned URL is a bearer URL, which is not subject to access-control. We consume it outside the realm of the Storage SDK, as a regular URL.

Note: the URL remains valid unless manually revoked at the file level in the Firebase Console.

```ts
getDownloadURL(fileRef).then(url => ...)
```

### consume a cross-origin HTTP URL on the client.

The URL is _cross-origin_. The challenges and patterns to consume a _cross-origin_ URL are not specific to Firebase.

Buckets do not have permissive CORS headers by default, but we may add them on demand. As a reminder, CORS headers may whitelist one, several or all domains. We use _gsutil_ or _gcloud_ to whitelist our domain, if necessary (see the dedicated chapter).

The way we consume the URL determines if CORS headers are necessary.

-   The browser allows _cross-origin_ URLs in media elements' _src_ attribute (hot linking), with no CORS headers required.
-   The browser allows navigating to _cross-origin_ URLs (basic browser behavior). For example, we navigate to an image in a new tab.
-   The browser _doesn't allow_ background fetch of cross-origin resources unless explicit CORS headers are present on the server. This applies to _fetch()_ and functions that rely on it.

### download a Blob with the client SDK

A blob is an opaque object that we can transform to a local URL. When downloading a Blob with the SDK's _getBlob()_:

-   access rules are enforced
-   CORS headers are required (it uses _fetch()_ under the hood)

When we create a _local_ (_same-origin_) URL out of the blob, we avoid the browser restrictions related to _cross-origin_ URLs. It restores the ability to download content through a single click, without navigating to a different URL (see below).

```ts
getBlob(fileRef).then((blob) => {
    // create a local URL and trigger download imperatively
})
```

### URLs in anchor tags and the download attribute

The _download_ attribute on an anchor tag (`<a href="" download>`) aims to offer one-click downloads. The pattern only works for _same-origin_ URLs or _local_ URLs.

For _cross-origin_ URLs, clicking the anchor tag triggers standard browser navigation instead: the browser navigates to the resource and shows its full URL.

### create a local URL out of a blob (browser specific)

This examples creates a local URL, triggers download programmatically and revokes the local URL for clean up.

```ts
// 3. Create a local URL for the blob
const objectURL = URL.createObjectURL(blob)

// 4. Use the local URL to trigger the download
const link = document.createElement("a")
link.href = objectURL
link.download = img.id + ".png"
document.body.appendChild(link)
link.click()
document.body.removeChild(link)

// 5. Clean up by revoking the local URL
URL.revokeObjectURL(objectURL)
```

# Upload data



## client SDK

### upload a _Blob_ or a _File_

We prepare some data in a JavaScript _Blob_ or _File_ object, and upload it to the reference.

```ts
const result = await uploadBytes(fileRef, file)
```

-   The upload is a non-conditional upsert which overrides any existing file.
-   It makes the file immediately _downloadable_ with the SDK read functions.
-   On success, we receive an _UploadResult_, which wraps the bucket file's metadata and the file reference.

```ts
result.metadata // FullMetadata
result.ref
```

### (advanced) upload and track the progress

For each tick, we receive a snapshot. We may show the upload progress.

```ts
const uploadTask = uploadBytesResumable(ref, file)

uploadTask.on(
    "state_changed",
    /* on snapshot */
    function (snapshot) {
        // snapshot.bytesTransferred
        // snapshot.totalBytes
        // snapshot.state // "paused" | "running"
    },
    function (error) {},
    function () {
        /* on completion */
        getDownloadURL(uploadTask.snapshot.ref).then(/**/)
    }
)
```

## admin SDK

### upload a Node.js _Buffer_ and make it downloadable

We prepare some data in a Node.js _Buffer_, and upload it to the reference.

```ts
await fileRef.save(imageBuffer, {
    resumable: false,
    metadata: {
        contentType: `image/png`,
        cacheControl: "public, max-age=31536000, immutable",
    },
})
```

Note: it doesn't make the file _downloadable_ for clients: a client _getDownloadURL()_ fails. This is because the underlying GC storage object is missing a Firebase-specific download token in its metadata.

To make it _downloadable_ for clients, we use the admin SDK's `getDownloadURL()`. It attaches a download token to the underlying GC storage if needed. It also returns a bearer URL (that embeds this very access token and is not subject to security rules). We can store the bearer URL in a database, send it to the client, or discard it since the client can create the URL by itself with its own `getDownloadURL()`.

```ts
const url = await getDownloadURL(fileRef)
```

We may invalidate an access token at any time, from the Firebase console. If we hardcoded bearer URLs in a database, they become invalid.

### advanced: controlling the CG object token field

The token, if any, is at the _firebaseStorageDownloadTokens_ metadata's field.

```json
metadata: {
  firebaseStorageDownloadTokens: token
}
```

### upload image example (admin SDK)

We upload an image and make it readable by clients. We may store the bypass URL.

```ts
// 1.0 create a file reference
const fileRef = bucket.file(`generated/${userID}/cat.png`)

// 1.1 create a Buffer object
const imageBuffer = base64ToBuffer(base64Data)

// 1.2 upload the Buffer object
await fileRef.save(imageBuffer, {
    resumable: false,
    metadata: {
        contentType: `image/png`,
        cacheControl: "public, max-age=31536000, immutable",
    },
})
//  1.3 make it readable by client SDKs (generate a token).
const url = await getDownloadURL(fileRef)

//  1.4 store the bypass URL (if applicable)
//  ...
```

# Setting the bucket CORS header



Some read operations require the client's domain to be whitelisted by a CORS header. We list the authorized domains in a _cors.json_ file and send it to Google through the CLI, with `gcloud storage`.

_cors.json_

```json
[
    {
        "origin": ["https://imagetales.io", "http://localhost:5173"],
        "method": ["GET"],
        "maxAgeSeconds": 3600
    }
]
```

Send the json file:

```bash
gcloud storage buckets update gs://imagetales.firebasestorage.app --cors-file=cors.json
```

Describe the existing bucket CORS config

```bash
gcloud storage buckets describe gs://imagetales.firebasestorage.app --format="default(cors_config)"
```

### read operations that require a CORS whitelist

Generally, those are browser reads relying on asynchronous (background) fetches rather than navigating to the URL through an anchor tag:

-   _getBlob(fileRef)_ to get a _Blob_, which uses _fetch()_ under the hood.
-   _getBytes(fileRef)_ to get an _ArrayBuffer_, which uses _fetch()_ under the hood.
-   using _fetch()_ manually with a bearer URL we got with _getDownloadURL()_ or that we stored somewhere before.

# Cloud Functions



Cloud Functions is a serverless functions offering: we run code on servers operated by Google.

As it is a secure environment, we may run sensitive tasks: authenticate requests, perform server-side validation, use sensitive API keys, make sensitive writes to the database, and more.

The functions may trigger on spontaneous requests, or on events happening in the Firebase ecosystem, such as the registration of new users through Firebase Auth.

### react to spontaneous requests: two options

The first option is to establish a bare-bones REST-API endpoint, called a `HTTP` function. It exposes a regular REST API endpoint, with an Express.js like API.

The second option is to establish a `Callable` function, a pattern that involves both a server SDK and a client SDK, which work hand in hand to provide a better developer experience, such as having built-in authentication support.

`onRequest` and `onCall` are the two helpers to define those function. They live in `https`.

```ts
import { onRequest, onCall } from "firebase-functions/https"
```

### select and deploy functions

The main file exports the functions we want to deploy. The main file is the one we define as so in _package.json_:

```json
{
    "main": "lib/index.js"
}
```

It is usually a barrel file that re-exports function implemented in their own file:

```ts
export { requestPlayer } from "./requestPlayer.js"
```

We deploy functions imperatively. We deploy one or all of them:

```bash
firebase deploy --only functions
firebase deploy --only functions:requestPlayer
```

To delete a function, we remove it from the main file and run the deploy command on it. The CLI detects it is missing and prompts us for confirmation.

### define functions with TypeScript

The main file must be a JavaScript file. We use a workflow that transpiles to JS. The convention is to store TS code in `src/` and transpile to `lib/` so that the main file is `lib/index.js`.

The _tsconfig.json_ file fits projects running on Node.js:

```json
{
    "compilerOptions": {
        "module": "NodeNext",
        "moduleResolution": "nodenext",
        "outDir": "lib",
        "esModuleInterop": true,
        "noImplicitReturns": true,
        "noUnusedLocals": true,
        "sourceMap": true,
        "strict": true,
        "target": "es2017"
    },
    "compileOnSave": true,
    "include": ["src"]
}
```

We ask the transpile to be continuous with the watch flag. The emulator detects the change in the JS functions and update them on the fly:

```bash
tsc -w
```

### admin SDK

Within functions, we interact with Firebase services such as databases and storage with the admin SDK. For example, we may work with the project's Firestore database:

```ts
import { initializeApp } from "firebase-admin/app"
import { getFirestore } from "firebase-admin/firestore"

const app = initializeApp()
const db = getFirestore(app)
```

# Define Callable functions



The code we run in a Callable function has access to the user authentication status and the request's data.

Callable functions support streaming the response: we describe it in a dedicated section.

## Overview and syntax

### synopsis

```ts
onCall<ReqData, Promise<ResData>>(callback)
onCall<ReqData, Promise<ResData>>(options, callback)
```

### the callback

The callback has access to the request ([CallableRequest](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.https.callablerequest)), which exposes _auth_ and _data_.

We define the callback async so it returns a promise. The connection is kept open until the promise settles.

```ts
onCall<ReqData, Promise<ResData>>(async (request) => {
    request.auth // AuthData | undefined
    request.auth?.uid

    request.data // ReqData

    return { message: ".." } // ResData
})
```

-   _auth_ is _undefined_ when the request is unauthenticated. It has _uid_ otherwise.
-   _ReqData_ defines the data sent by clients.
-   _ResData_ defines what the callback returns.

### set options

_onCall_ accepts an optional _options_ object, of type _CallableOptions_, a subclass of [GlobalOptions](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.globaloptions.md#globaloptions_interface), as the first argument.

```ts
const options: CallableOptions = {
    concurrency: 1, // how many
    minInstances: 1,
    maxInstances: 1,
    region: "europe-west1",
}
```

_concurrency_ sets how many request a single instance may process in parallel. By default, a single instance processes multiple requests in parallel. We set it to one if we prefer sequential request processing, assuming we also set _maxInstances_ to 1.

_minInstances_ default to 0. To avoid cold starts, we can set _minInstances_ to 1 but it costs more as it is warm all the time.

## Streaming version

The _request_ has `acceptsStreaming`, which we read to check if the client supports streaming. When it does, the callback has access to a _response_ argument, on which we call _response.sendChunk()_.

Streaming the response means to send small chunks of data with _sendChunk()_.

The third type argument defines what kind of chunk we stream. We usually stream _string_ chunks.

```ts
onCall<T, U, V>(options, callback) // streaming Callable
```

```ts
onCall<ReqData, Promise<ResData>, StreamData>(async (request, response) => {
    response?.sendChunk("abc") // StreamData
    response?.sendChunk("def")

    return { message: ".." } // fallback
})
```

## Patterns

### halt and send an error immediately

We throw an _HttpsError_ instance with a specific error code string which conforms to a [predefined list](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.https.md#httpsfunctionserrorcode). If we omit the error code, it defaults to an _internal error_ kind of error.

```ts
throw new HttpsError("unauthenticated", "unauthenticated")
```

### endpoint naming: request + action

using _request_ denotes that the server may refuse to perform the action. It separates the request from the action proper, which may live in another file.

### logger

todo

## Callable v1 (deprecated)

### define the function

```ts
functions.https.onCall(async (data, context) => {
    const auth = context.auth
    const message = data.message
    return { message: ".." }
})
```

### the context object

The context object provides the authentication details, if any, such as
the email, and the request metadata such as the IP address, or the raw
HTTP request. It is of type [CallableContext](https://firebase.google.com/docs/reference/functions/firebase-functions.https.callablecontext)

### check authentication

```ts
if (!context.auth) {
    throw functions.https.HttpsError("unauthenticated", "you must be authenticated")
}
```

# Invoke Callable functions



We get a reference to the callable function, and call it like a regular function.

### specify the firebase project and the region

Since a client may interact with Cloud Functions from separate Firebase projects, we specify the project we target. We do so indirectly, by providing the _app_ helper, which already identifies the project.

Since a function may deploy across regions as separate _regional instances_, we specify which instance we target. We use one of the regional identifiers defined in the Callable options. If omitted, the client SDK targets `us-central1`, which errors if no instance runs there.

Note: we set the region identifier at the _getFunctions()_ level. That is, the _functions_ helper is region-aware:

```ts
const functions = getFunctions(app, "europe-west1")
```

### get a handle over the Callable function

We provide the function's name to `httpsCallable()`.

```ts
const requestPokemon = httpsCallable<ReqData, ResData>(functions, "requestPokemon")
```

### invoke and handle the result

We provide a payload, if applicable, of type `ReqData`. The result is of type `HttpsCallableResult<ResData>`. If it succeeds, we access the data:

```ts
const result = await requestPokemon({ number: 151 })
result.data // ResData
```

# HTTP functions



### overview

Establish a bare-bones REST-API endpoint, called a `HTTP` function. We expose a regular REST API endpoint, with an Express.js like API.

We respond with JSON, HTML, or any other format.

```ts
export const sayHello = onRequest((req, res) => {
    res.send("Hello from Firebase!")
})
```

### options argument

```ts
const options = {
    region: "europe-west1",
    cors: true,
}
export const sayHello = onRequest(options, (req, res) => {})
```

### ExpressJS concepts and syntax

We may use middleware. Req and res objects have the shape of an expressJS req and res objects.

### invoke the function: standard HTTP request.

This is not specific to Firebase. From a web client, we use fetch().

We use the POST method and can provide a payload

# Functions on Auth events



Register functions that listen and react to Firebase Auth events.

## Blocking functions

### run a function before the user is added to Firebase Auth

The Authentication service waits for the function to complete successfully before adding the user. If the function throws, the user is not created, and an error is thrown to the client stating that the registration failed.

```ts
const options: BlockingOptions = {
    region: "europe-west1",
}

export const onRegisterBlocking = beforeUserCreated(options, async (event) => {
    const user = event.data // AuthUserRecord === UserRecord
    // user.uid
    // user.email
    if (user?.email?.includes("@hotmail.com")) {
        throw new HttpsError("invalid-argument", "don't use hotmail")
    }
    // create the user in the database first, then return
    await createDefaultDataForUser(user)
    return
})
```

## Non blocking functions

The non blocking functions run _after_ a user has been created or deleted by Firebase Auth.

Firebase Auth manages a list of users. It's best to mirror them in a database.

As of writing, there is no _v2_ version for the non blocking functions.

```ts
export const f = auth.user().onCreate(async (user) => {})
export const g = auth.user().onDelete(async (user) => {})
```

### example: add the user to the Firestore database

```ts
import { region } from "firebase-functions/v1"
import { db } from "../firebaseHelper.js"

export const onRegisterNonBlocking = region("europe-west1")
    .auth.user()
    .onCreate(async (user) => {
        const { uid, email } = user
        // add user to Firestore
        await db.collection("users").doc(uid).set({
            uid,
            email,
        })
        return
    })
```

### example: delete the user from the Firestore database

```ts
import { region } from "firebase-functions/v1"
import { db } from "../firebaseHelper.js"

export const onDeleteAccount = region("europe-west1")
    .auth.user()
    .onDelete(async function (user) {
        const { uid } = user
        await db.doc("users/" + uid).delete()
        return
    })
```

# Functions on Firestore events



```ts
functions.firestore
functions.firestore.document()
```

Validate the data sent by a user to the database. Make sure they don't
send incorrect data. This helps preserve data integrity.

```ts
exports.myFunction = functions.firestore
    .document("my-collection/{docId}")
    .onWrite((change, context) => {
        /* ... */
    })
```

## on Storage events

```ts
functions.storage
```

the user uploads a file to Firebase Storage

perform data validation and transform

### React to completed files uploads:

```ts
exports.generateThumbnail = functions.storage.object().onFinalize(async (object) => {
    const fileBucket = object.bucket
    // The Storage bucket that contains the file.
    const filePath = object.name
    // File path in the bucket.
    const contentType = object.contentType
    // File content type.
    const metageneration = object.metageneration
    // Number of times metadata has been generated. New objects have a value of 1.
})
```

[Create a thumbnail for an uploaded image.](https://github.com/firebase/functions-samples/blob/313de92ff1612dd6b3c2ee9320d269aee9b8045d/quickstarts/thumbnails/functions/index.js#L58-L78)

# JS Dates and Callable Functions



### ISO strings are the better choice

When interacting with Callable Functions, it's best to represent dates as _ISO strings_. It is simple to reason about: the value and the type stay consistent on the client and on the server.

If we were to work with Date fields or even Firestore Timestamps fields, the value and the type are not consistent when both sending to the server and when receiving from the server. As such, it is a discouraged pattern.

In this article, we explain what happens if we send _Date_ and _Timestamp_ objects to Callable Functions or if we send them to the client from Callable functions. Before being sent, both are serialized to JSON.

### sending to Callable Functions

_Timestamp_ is a Firestore specific type and doesn't get a special treatment: it serializes to an object with _seconds_ and _nanoseconds_ (through _toJSON()_).

```
timestamp: { seconds: 1696751687, nanoseconds: 527000000 },
```

As for fields of type _Date_, they serialize to an ISO string (through _toJSON()_):

```ts
date: "2023-10-08T07:54:47.527Z"
```

We could technically instantiate a Timestamp or a Date:

```ts
new Timestamp(timestamp.seconds, timestamp.nanoseconds)
new Date(date)
```

### sending from Callable functions

If we attempt to return a Date object, it serializes to an ISO string.

If we attempt to return a Timestamp object, it serializes to the internal representation, possible an object with _\_seconds_ and _\_nanoseconds_. We should avoid this pattern.

# Environment variables



### firebase secrets pattern

we provide secrets through the CLI tool. We may then request some cloud functions to expose the secrets as Node.js process environment variables.

```bash
firebase functions:secrets:set ABC_API_KEY
```

### .env file pattern

[env-variables docs](https://firebase.google.com/docs/functions/config-env?gen=2nd#env-variables)

we may set the env variables in a .env file

    ABC_API_KEY=xxx

the .env should not be versioned. At function deployment, the firebase CLI tool sends the .env file to firebase servers.

### read from env

read env within cloud functions

    process.env

callable function: indicate the environment variables dependencies, that firebase should expose on the _process.env_

```ts
const options: CallableOptions = {
    region: "europe-west1",
    secrets: ["ABC_API_KEY"],
}

onCall<ReqData, Promise<ResData>>(options, async (request) => {
    const abcKey = process.env.ABC_API_KEY
})
```

onRequest

```ts
const options = { secrets: ["ABC_API_KEY"] }

onRequest(options, (req, res) => {
    process.env.ABC_API_KEY
})
```

### debug secrets

```bash
gcloud secrets list --project <PROJECT_ID>
```

## v1 (deprecated)

Tell firebase to save a token/key on our behalf so that we can access it
by reference in code, without writing the actual key in code and in git
as a result.

```bash
firebase functions:config:set sendgrid.key="...." sendgrid.template="TEMP"
```

### Read from Env

Firebase exposes the tokens/keys in an object we get through the
config() method.

```ts
const API_KEY = functions.config().myKey
```

# Debug Functions locally



### turn on functions in the emulator

We run the functions on their own or with other emulators.

```bash
npm run serve
firebase emulators:start --only functions

firebase emulators:start --import emulator-data --export-on-exit
```

### invoke emulated functions from a CLI shell

The _shell_ command also starts an interactive CLI shell from which we can invoke Callable functions with data arguments.

The command starts the emulator and connects a CLI REPL shell session to it so that we may trigger the functions from the CLI:

```bash
firebase functions:shell
npm run shell # alternative
```

call a Callable function from the CLI: we add the request's payload to the mandatory `data` property.

```ts
requestArticles({ data: { name: "Lena" } })
```

### invoke emulated functions from the client SDK

We redirect invocations towards the emulated functions, but only on _localhost_:

```ts
if (location.hostname === "localhost") {
    // ...
    connectFunctionsEmulator(functions, "localhost", 5001)
}
```

### make direct HTTP requests to non-Callable functions

The HTTP functions' URL follows a specific pattern:

```
<HOST>/<PROJECT-ID>/<REGION>/<FUNC_NAME>
http://localhost:5001/imgtale/europe-west1/request_articles
```

```bash
curl -s -H "Content-Type: application/json" \
  -d '{ "data": { } }' \
  http://localhost:5001/imgtale/europe-west1/request_articles
```

# Schedule execution: Cron jobs



### schedule periodic code execution

To define a schedule, we set both the periodicity and the timezone. We set the periodicity, we use strings such as `every day 00:00` or `every 8 hours`. Then we also provide the callback function.

```ts
export const updateRankingsCRON = onSchedule(
    {
        schedule: "every day 00:00",
        timeZone: "Europe/Paris",
        region: "europe-west1",
    },
    async () => {
        // ...
    }
)
```

The former version (v1) uses a different API:

```ts
export const updateRankingsCRON = functions.pubsub
    .schedule("every 8 hours")
    .timeZone("Europe/Paris")
    .onRun(async (context) => {
        // ..
    })
```

# GenKit



### overview

Genkit enables interacting with LLM providers through a single, unified interface. It allows us to compose prompts together within a flow. It also offers a UI to test and debug prompts and flows.

### packages

```bash
genkit
@genkit-ai/compat-oai
@genkit-ai/compat-oai/openai # import
dotenv #to embed tokens

#genkitx-openai #deprecated
```

https://github.com/firebase/genkit/tree/main/js/plugins/compat-oai

### quick setup

get an ai provider with `genkit()`

```ts
import { genkit } from "genkit"
import openAI, { gpt4o } from "genkitx-openai"

const ai = genkit({
    plugins: [openAI({ apiKey: process.env.OPENAI_API_KEY })],
    model: gpt4o,
})
```

### quick request with an inline prompt

The inline prompt may be used for simple usecases or for prototyping.

trigger the request with `generate()` or `generateStream()`. It expects an arguments object, with a `prompt` property, and other optional properties

```ts
const { text } = await ai.generate({
    prompt: `Pick a number between 222 and 333`,
})
return text
```

### stream the response

We call `generateStream()`. _stream_ is an async iterable, so we may iterate over it with `for await`.

```ts
const { response, stream } = ai.generateStream({
    prompt: `Pick a number between 222 and 333`,
})

for await (const chunk of stream) {
    process.stdout.write(chunk.text) // debug in stdout
}
// we may still use the complete response
const completeText = (await response).text
```

# .prompt Prompt file



### overview

The prompt file, also called a `dotprompt` file, is a text file with a `.prompt` extension. It contains the prompt, along with some metadata. The metadata lives at the top, in the file's front matter.

### prompt

We may use a fixed prompt or a template prompt:

-   The fixed prompt is not customizable and is used as-is.
-   The template prompt is a piece of text that includes slots, which makes it customizable. The caller provides data to customize the prompt.

```yaml
Translate to english: { { character } }
```

### front matter

the front matter follows a YAML syntax, and provides metadata.

```yaml
---
name: requestExamples
model: openai/gpt-4o
config:
    temperature: 0.5
---
```

### front matter for a template prompt

If the prompt is to receive arguments, we define their name, type and default value in the front matter.

The arguments live in the `input` object. `schema` provides the types, while `default` provides the default values.

```yaml
___
...
input:
	schema:
		character: string
	default:
		character: 我
---

Translate to english: {{character}}
```

### reference the prompt file

We provide the prompt file path. `prompt()` returns an object of type _ExecutablePrompt_.

```ts
const requestExamples = ai.prompt("requestExamples")
```

### run the prompt file

We may use the handle to trigger the request.

```ts
// wait for completion
const { text } = await requestExamples({ character: "菠萝" })
// stream
const { stream } = requestExamples.stream({ character: "菠萝" })
```

# TypeScript Prompt file



Using TypeScript to define the prompt allows us to type the arguments and benefit from autocomplete for the model name.

We define a prompt with `definePrompt()`:

```ts
import { ai } from "../utils/ai"
import { gpt41 } from "genkitx-openai"
import { z } from "zod"

export const requestExamples = ai.definePrompt({
    name: "requestExamples",
    model: gpt41.name,
    input: {
        schema: z.object({
            character: z.string(),
        }),
    },
    prompt: `Make 3 example sentences for the character {{character}}.
  Provide the english translation but not the pinyin. Do not comment`,
})
```

### call the prompt

call the prompt and wait for the full response

```ts
const { text } = await requestExamples({ character: "菠萝" })
```

call the prompt and stream the response

```ts
const { stream, response } = requestExamples.stream({ character: "菠萝" })

    for await (const chunk of stream) {
        ...
    }
```

Firebase

Editing and staging

Common commands

Branches

Remote

Stashing unsaved work

Other

Internals

# Overview

<div class="bookHeroImage" style="padding: 32px;margin: 8px 0;">
<svg xmlns="http://www.w3.org/2000/svg" width="292" height="92pt" viewBox="0 0 219 92">
    <defs>
        <clipPath id="a">
            <path d="M159 .79h25V69h-25Zm0 0"/>
        </clipPath>
        <clipPath id="b">
            <path d="M183 9h35.371v60H183Zm0 0"/>
        </clipPath>
        <clipPath id="c">
            <path d="M0 .79h92V92H0Zm0 0"/>
        </clipPath>
    </defs>
    <path style="stroke:none;fill-rule:nonzero;fill:#362701;fill-opacity:1" d="M130.871 31.836c-4.785 0-8.351 2.352-8.351 8.008 0 4.261 2.347 7.222 8.093 7.222 4.871 0 8.18-2.867 8.18-7.398 0-5.133-2.961-7.832-7.922-7.832Zm-9.57 39.95c-1.133 1.39-2.262 2.87-2.262 4.612 0 3.48 4.434 4.524 10.527 4.524 5.051 0 11.926-.352 11.926-5.043 0-2.793-3.308-2.965-7.488-3.227Zm25.761-39.688c1.563 2.004 3.22 4.789 3.22 8.793 0 9.656-7.571 15.316-18.536 15.316-2.789 0-5.312-.348-6.879-.785l-2.87 4.613 8.526.52c15.059.96 23.934 1.398 23.934 12.968 0 10.008-8.789 15.665-23.934 15.665-15.75 0-21.757-4.004-21.757-10.88 0-3.917 1.742-6 4.789-8.878-2.875-1.211-3.828-3.387-3.828-5.739 0-1.914.953-3.656 2.523-5.312 1.566-1.652 3.305-3.305 5.395-5.219-4.262-2.09-7.485-6.617-7.485-13.058 0-10.008 6.613-16.88 19.93-16.88 3.742 0 6.004.344 8.008.872h16.972v7.394l-8.007.61"/>
    <g clip-path="url(#a)">
        <path style="stroke:none;fill-rule:nonzero;fill:#362701;fill-opacity:1" d="M170.379 16.281c-4.961 0-7.832-2.87-7.832-7.836 0-4.957 2.871-7.656 7.832-7.656 5.05 0 7.922 2.7 7.922 7.656 0 4.965-2.871 7.836-7.922 7.836Zm-11.227 52.305V61.71l4.438-.606c1.219-.175 1.394-.437 1.394-1.746V33.773c0-.953-.261-1.566-1.132-1.824l-4.7-1.656.957-7.047h18.016V59.36c0 1.399.086 1.57 1.395 1.746l4.437.606v6.875h-24.805"/>
    </g>
    <g clip-path="url(#b)">
        <path style="stroke:none;fill-rule:nonzero;fill:#362701;fill-opacity:1" d="M218.371 65.21c-3.742 1.825-9.223 3.481-14.187 3.481-10.356 0-14.27-4.175-14.27-14.015V31.879c0-.524 0-.871-.7-.871h-6.093v-7.746c7.664-.871 10.707-4.703 11.664-14.188h8.27v12.36c0 .609 0 .87.695.87h12.27v8.704h-12.965v20.797c0 5.136 1.218 7.136 5.918 7.136 2.437 0 4.96-.609 7.047-1.39l2.351 7.66"/>
    </g>
    <g clip-path="url(#c)">
        <path style="stroke:none;fill-rule:nonzero;fill:#f03c2e;fill-opacity:1" d="M89.422 42.371 49.629 2.582a5.868 5.868 0 0 0-8.3 0l-8.263 8.262 10.48 10.484a6.965 6.965 0 0 1 7.173 1.668 6.98 6.98 0 0 1 1.656 7.215l10.102 10.105a6.963 6.963 0 0 1 7.214 1.657 6.976 6.976 0 0 1 0 9.875 6.98 6.98 0 0 1-9.879 0 6.987 6.987 0 0 1-1.519-7.594l-9.422-9.422v24.793a6.979 6.979 0 0 1 1.848 1.32 6.988 6.988 0 0 1 0 9.88c-2.73 2.726-7.153 2.726-9.875 0a6.98 6.98 0 0 1 0-9.88 6.893 6.893 0 0 1 2.285-1.523V34.398a6.893 6.893 0 0 1-2.285-1.523 6.988 6.988 0 0 1-1.508-7.637L29.004 14.902 1.719 42.187a5.868 5.868 0 0 0 0 8.301l39.793 39.793a5.868 5.868 0 0 0 8.3 0l39.61-39.605a5.873 5.873 0 0 0 0-8.305"/>
    </g>
</svg></div>

### traditional save patterns without git

The traditional save pattern is to store a file in-place or to a new file.

Saving in place is destructive: it does not preserve the old version.

Saving to a new file is safe, but leads to another challenge: managing multiple versions, their names, the storage and the retrieval, which is cumbersome and error-prone.

### software source code specifics

Software source code usually consists of a tree of files that, together, make a whole unit. Compiling the software usually requires to have the whole tree available as-is on the filesystem.

As such, an actionable snapshot is one that comes as a whole.

The naive way to store snapshots is to store the whole file tree for any given file change. This method has a heavy and inefficient storage footprint, due to spreading identical files across snapshots.

### what we want from a versioning software

We want an approach that is more efficient in terms of storage: the snapshots should not be stored as-is, but instead be reconstructed on-demand, with files being fetched from a central storage. The software should keep track of the files that a given snapshot relies on.

We want to conveniently browse and load old snapshots or snapshots from alternative development branches.

We also want snapshots to come with metadata: their date, their unique ID, and the description of changes they bring (commit message).

### lightweight snapshot: a declarative list of files

We have the snapshot as a declarative list of files it is comprised of, like a shopping list.

In this pattern, the files may live anywhere. This allows files to be referred to by any snapshot, and to be stored only once.

The software may reconstruct the snapshot based on the list: the software fetches the files from the storage and builds a snapshot mirror.

### editing area

The local directory where we make changes is called the `working directory` or `working tree`.

Most of the time, it should start as a mirror of the latest snapshot, allowing to work on changes and submit a new snapshot for commit.

Sometimes, it will instead mirror an old snapshot, so that we may run the snapshot as it was, or to fork away from that snapshot onwards.

### other terminology

to commit means to intentionally save a snapshot. By extension, we may refer to a snapshot itself as a commit. In git internals, a commit is the file that stores all the file dependencies and the metadata related to a given snapshot.

The `staging area`, also called the `index`, is a tentative snapshot, on that is ready to be committed. See _Editing and staging_.



# Editing and staging

### separation of concern: working directory and staging area

We keep the working directory and the staging area (index) separate to acknowledge their different role.

### the role of the working directory

The working directory is a playground where changes are not saved, good for exploration and iteration. Its content has no influence on what is saved when we perform a commit.

### terminology

This allows us to have files that we don't commit yet or ever: _untracked_ files. If the file is a modified version of one that was committed before, and that it is not staged yet, we call it _modified_.

When files are added to the staging area, they cease to be _untracked_ or _modified_: they become _staged_.

### staging area: granularity and storage

The staging area determines what is saved on commit. Having some granularity instead of saving the whole working tree has benefits:

-   We may select related changes and commit them as a group.
-   We may technically save different portions of a file at a time.

Besides, we may use the index as a temporary storage, in a manner similar of saving checkpoints: This allows to store one version and keep iterating on it, with the ability to revert to the checkpoint if needed.

This is possible because the index is similar to a commit: it has its own list of files, which live in the storage area, and that are decoupled from the working tree.



# Common commands

the standard workflow is as follows:

-   make some changes to one or more files in the working directory
-   select one or more changes, put them in the staging area
-   save the staging area as a commit.

## standard flow

### stage files: working-directory to index

`git add` adds one or more files to the staging area. It affects both _untracked_ files and _modified_ files, turning them into _staged_ files.

```bash
git add .
git add -u
```

We may exclude _untracked_ files from staging with `-u`. A more permanent solution is to add them to `.gitignore`.

### commit: index to commit

Save the staging area as a new commit. It has no effect over the working directory:

```bash
git commit -m "..."
```

We may edit the last commit message with `--amend`. This does not create a new commit.

```bash
git commit --amend -m "an updated commit message"
```

Note: the `-am` flag is not a shortcut for both `git add .` and `git commit -m ''`, since it does not add _untracked_ files.

```bash
git commit -am "adding and committing modified files"
```

## reverting to the last commit

The last commit is commonly represented by `HEAD`.

### commit to working-directory: reset the working-directory.

we use `restore` and set the `--source` to HEAD.

```bash
git restore --source=HEAD --worktree  .
git restore --source=HEAD .
```

old syntax

```bash
git checkout HEAD   -- . 				# the last commit
git checkout v1.2.3 -- .      # tag v1.2.3
git checkout stable -- file   # stable branch
git checkout origin/master -- file  # upstream master
git checkout HEAD^ -- file          # the version before the last commit
```

### commit to working-directory AND index.

We aim to revert both the index and the working directory to the commit version.

It does not affect or remove untracked files, since they are ignored by git.

```bash
git restore --source=HEAD --staged --worktree .

git reset --hard
```

### commit to index: reset the staging area

We may revert the staging area to the clean state of the previous commit. The working tree is unaffected.

We use the _restore_ command, with the _staged_ flag.

```bash
git restore --staged . # tested
git reset .
```

If we are before the first commit, we may remove content from the staging area:

    git rm --cached file
    git reset

## reverting to the index version

### index to working-directory: go back to the index checkpoint

We may restore the worktree from the index. This may restore a checkpoint or the last commit, depending on the content of the staging area.

The `restore` and `checkout` command implicitly restore the worktree from the staged area. We may make it more explicit by setting flags.

```bash
git restore .
git restore --worktree . #same
git restore file
```

```bash
git checkout .
git checkout main.js
```

## reverting to older commits

### revert the current branch to a previous commit

Restaurer la version de travail, la version staged et la version
sauvegardée depuis la sauvegarde précédente nommée explicitement ou
relativement par le nombre de commit depuis cette sauvegarde.

revenir au commit spécifié explicitement.

```bash
git reset --hard 2bje9dlhash
```

revenir au commit à une distance de N par rapport au dernier commit, ici
l'avant dernier commit.

```bash
git reset --hard HEAD^1
```

## other commands

### remove untracked files

delete untracked files

```bash
git clean -fd
```

delete untracked files and files present but ignored by git

```bash
git clean -fdx
```

dry run

```bash
git clean -fdn
git clean -fdxn
```



# Branches

### a line of commits and the last commit on a line

A list of commits can be seen as a line in the sense of a continuous list of snapshots that follow each other. Technically, each commit keeps a reference to its parent (the former commit), so that we may reconstruct a whole line from a given commit.

We may conceptualize a branch as a line of a commits that lead to a tip commit.

There are as many distinct theoretical branches as there are commits, and we may have several actual branches pointing to the same commit.

All it takes to create a branch is to pick a name and decide what commit it points to. This commit becomes the current tip of the branch.

Branches are independent from each others: they allow to work in isolation. When we add a commit, the active branch is updated to point to the new commit, while others are untouched.

### branches that live on the same line: fast-forward compatible

We may say that two branches live on the same line when the longer branch is the continuation of the shorter branch. The tip of the longer branch is a descendant of the tip of the short branch.

To fast forward a branch is to bring it closer to, or at the same point than a longer branch that lives on the same line. Technically, we make it point to a more recent commit on the line.

while the git command we use is called _merge_, there is no graph merge during a fast-forward.

### branches that have forked: eligible for a merge commit

One branch has forked from the other one. The last commit they have in common is the common ancestor. The merge commit is one that aims to merge the paths coming from two parents. As such, it is a special commit that points to two parents instead of one.

Git compares files across the two parents and, when they are different, checks if one of them is _stalled_, aka has not changed since the last common ancestor. In that case, it favors the one that has received work, as it assumes the merge intends to make use of such work.

If both paths have worked on the ancestor version to change it, the merge cannot pick one version on its own. It asks the developer to resolve the difference between the two parents.

### add the merge commit to the receiving branch

Once the merge commit has been created, the merge process doesn't merge the two branches into one, neither does it make both branches point to it.

Instead, the merge commit is only added to the _receiving_ branch. The receiving branch is now "aware" of the two paths that led to the merge commit.

The other branch stays as-is. It is eligible for fast forward toward the receiving branch.

### merge one branch (ex:dev) to current (ex:main) (repetition)

We first compare the two branches: the receiving branch (current), and
the giving branch.

If the receiving branch is a parent of the giving branch, that is, it
has not drifted away because it didn't do any commit on its own, then we
can simply fast forward the receiving branch to the state of the giving
branch, making them point to the same commit.

If the receiving branch has done at least one distinct commit, it means
there was an actual fork, and a merge commit is required, to integrate
the branch that has forked, and to preserve the fact that there was a
fork. The merge commit only occurs on the receiving branch.

For example, we merge dev into main. dev is unaffected. main has a merge
commit.

## commands

### list branches

```bash
## list branches
git branch
## includes remote-tracking branches
git branch -a
```

### create, rename, delete branch commands

creating a branch does not switch to it.

```bash
git branch dev
git branch -m master main
git branch -d dev
```

### branch switching

switching to a branch means to have HEAD pointing to the branch, which points to a commit. The idea of switching to a commit is to get a clean working directory and index that match this commit, so we may start working from this snapshot.

```bash
git switch dev
```

### switching to a branch that comes from a remote

if the remote branch such as _origin/dev_ does not have a matching local branch, the git switch command may create the _dev_ local branch and switch into it.



# Remote

### instances and the canonical repository.

A remote repository is an instance of the repository that lives at another location.

There is no built-in hierarchy between instances. When there is a conflict, it's up to users to resolve it.

We use a pattern that sets one instance as the source-of-truth, with some flexibility when it needs to be corrected. We name it the _canonical repository_.

In practice, we put the canonical repository on a server known by all team members. Each member pushes changes to it and pulls changes from it.

For example, a member sets up a repository and publishes it to a host such as Github. The hosted repository becomes the _canonical repository_. Then, members clone the repository. _Cloning_ downloads the repository and pre-configures it to be linked with the _canonical repository_.

### remote-tracking branch

the remote-tracking branch mirrors a branch that lives on a remote repository, usually the canonical repository. As a faithful mirror, it is read-only, and only changes through a network call that signals changes.

we may poll the remote repository with `git fetch`. If updates are found, Git downloads the related commits and add them to the remote-tracking branches. We may inspect them like any other branch: we may log the commits and check the differences.

```bash
git log origin/main
git diff main origin/main
```

We may then merge the remote-tracking branch into the local-only one:

```bash
git merge origin/main
```

_git pull_ is a shortcut for _git fetch_ and _git merge_.

### remote

As a Git technical term, a _remote_ is a configured reference to a remote repository. We setup a remote to be able to push and pull from it.

We add a remote through its URL, and give it an alias name for convenience. By convention, we use _origin_ for the main repository remote.

```bash
git remote add origin https://github.com/user333/helloworld.git
```

We may list remotes and show information for a given one. It's usually only _origin_.

```bash
git remote show
git remote show origin

## remote origin
##   Fetch URL: https://github.com/user33/abc.git
##   Push  URL: https://github.com/user33/abc.git
##   HEAD branch: main
##   Remote branch:
##     main tracked
##   Local branch configured for 'git pull':
##     main merges with remote main
##   Local ref configured for 'git push':
##     main pushes to main (up to date)
```

### mutate a remote's URL

example: change the URL that _origin_ refers to

```bash
git remote set-url origin git@github.com:user33/abc.git
```

### merge the changes coming from remote

this is what happens when we do git pull (fetch + merge): the _fetch_
updates _origin/main_, then the merge applies a fast forward so that
main and origin/main point to the same commit.

```bash
git merge origin/main
```

### merge a branch into main

```bash
git merge <branch-name>
git merge dev
```

## clone: download and expand the .git directory

### download

a clone downloads the .git directory.

    https://github.com/mantinedev/mantine.git

we may clone a stripped-out version of the .git directory, one that
contains fewer files.

For example, we ask the files needed by the last commit, and not the
others. This is called a shallow clone.

We specify the depth, to target only the n-last commits.

```bash
git clone --depth 1 https://github.com/mantinedev/mantine.git
git clone --depth 1 [--branch master] https://github.com/mantinedev/mantine.git
```

### expand

the clone automatically expands the latest commit files into the working
directory.

## branches and remote

### push a branch that does not exist yet on the remote repository

Given that the remote repository doesn't have our local branch, we also don't have a remote-tracking branch that is supposed to track this branch on the remote. As such, we cannot set up an upstream just yet, because doing so requires binding a local-only branch to a remote-tracking branch.

Instead, we must first push the branch to the remote repository. If it is successful, we get the remote-tracking branch, and Git may now bind the branch to the remote-tracking branch, configuring it as the upstream.

We do it with one command: the `push` command, where we specify which _remote_ we are pushing to, which branch we are pushing, and that we want Git to make the upstream binding if the push was a success

```bash
git push -u origin 2024
```

### delete a branch on the remote repository

push is because it's an update to the remote repo.

```bash
git push origin --delete 2024
```

### indicate match between current branch and remote-tracking branch

```bash
git branch --set-upstream-to origin/my_branch
git branch -u origin/my_branch
```

### prune remote-tracking branches

We may have deleted some branches on the remote, and we want our repository to stop mirroring them:

```bash
git fetch --prune
```



# Stashing unsaved work

### dirty working tree

The working tree is dirty when it has _modified files_. They may represent unsaved work. _Untracked files_ live outside of Git, but may also represent unsaved work.

the _modified files_ that we added to the index became _staged files_. They also represent unsaved work.

There are a few scenario where Git has to clear up both the working tree and the index, to replace them with the content from another commit. This may occur when switching to a branch that points to another commit, or when merging some remote branch into our current one. (this does not occur when creating a branch because it keeps pointing to the current commit, keeping the current changes relevant)

The straightforward solution is to save the pending work into a new commit to make the working directory and index clean, and then perform the operation mentioned above.

### stashing and popping

In the case where we _don't want_ to create a commit, but we want to preserve the work that lives in the working tree and the index, we may ask Git to `stash -u` the changes. Under the hood, Git creates a hidden commit for the working tree and one for the index.

Later, we may reverse the operation, bringing back the unsaved work to the working tree and the index, with `pop --index`.

```bash
git stash
git stash -u # include the untracked files
```

Restore the working directory and staging area, assuming we are back on the correct branch. the --index flag restores the staging area as well.

```bash
git stash pop --index # if it worked without conflict

git stash pop --index
git stash drop # if conflict happened and has been solved

git stash apply --index # apply never drops the stash
git stash drop
```

### conflict resolution on pop

When popping the unsaved files back to the working tree, there may be a conflict. The conflict resolution is the same as the one for merge conflicts. If it cannot solve the conflict itself, it will expose the incompatible changes in the files with visible marks to let the developer pick one. Similar for merge conflicts, the developer edits the file and signals it as resolved by performing a `git add` on the file.

As Git is conservative, it does not clear the stash if a conflict was detected. After we have resolved the conflict, we may have to clear the stash manually.

advanced: If we attempt to pop back a file from the index into an index that has a distinct version that also received work, it will fail completely, since the manual resolution is not possible for files that are in the index.

###



# Other

edit the files without editing the message

    git commit --amend --no-edit

### example

    git init
    git add .
    git commit -m "initial commit"
    git remote add origin https://github.com/s3/aw33.git
    git push -u origin master

### diff

    git diff
    git diff --staged

The default diff is the one between the working tree and the staging area.

Once changes are staged, we may check the diff between the staging area and the last commit instead.

### information about latest commit

we may show information about a commit, including the diff, with the git
show command. It shows information about the last commit by default.

    git show

### prune .git folder, prevent some safeguards

### clean : supprimer aussi les untracked files et folders

    git clean -df

supprime les untracked files et directories. En effet, git checkout . ne
permet pas de supprimer les fichiers et directories qui sont untracked,
ramene a leur ancienne version seulement les fichiers tracked.

### log commits, forks and merges

we log the commits of the current branch

    git log

we may display the forks and merge commits

    git log --graph --oneline

### head

Head is which commit the working tree is coming from.

We change the head by checking out a specific commit.

When we check-in a commit that is not tracked by any branch, we say the
head is detached, probably meaning detached from any branch.



# Internals

### the .git directory serves as the git repository

In Git terminology, the git repository is the `.git` directory managed by git. It is a hidden directory that lives at the root of the project. It stores all versioning data.

Because the directory stores all the project's data, we sometimes conflate it with the project directory itself, the one that lives locally and that contains both the working tree and the git repository proper.

### enable git versioning in a project

The git init command creates the .git repository and enables git commands.

```bash
git init
```

### .git directory content

files and directories

    COMMIT_EDITMSG
    FETCH_HEAD
    HEAD
    ORIG_HEAD
    config
    description
    index
    packed-refs
    
    hooks/
    info/
    logs/
    objects/
    refs/

### project specific configuration

the configuration file lives at .git/config

```bash
open .git/config
```

### per user configuration

We may configure git at the user-level on a given computer. The configuration file is `.gitconfig` and lives in the home directory

```bash
code ~/.gitconfig
code ~/.gitattributes

git config user.name
git config user.email

git config user.name "John"
git config user.email "a@b.co"
```


Property list files

Application bundle

Application's persisted data

Launch processes automatically

Default directories and files

# Overview

### understand the macOS design choices

We discuss macOS conventions, patterns and defaults, and try to understand the design choices behind them.



# Property list files

A `.plist` file (Property List) commonly stores a set of user-preferences or some metadata about an app. It is a list of key-values.

The data's format is either binary or XML.

We may view or edit data with Xcode or `plutil`. We may use a text editor for XML ones.

```bash
plutil -p Info.plist
plutil -p "/Applications/Discord.app/Contents/Info.plist"
```

we may use `file` to detect if it's binary or XML:

```bash
file Info.plist
## Info.plist: XML 1.0 document text, ASCII text
```



# Application bundle



A pattern where we bundle the executable along with supporting files in a directory that looks like the application itself, at least in the Finder, as it has an `.app` suffix and as it comes with special behaviour and appearance:

-   The double-click runs the program instead of opening the directory
-   Finder shows the application's icon instead of a directory icon.

The content is semi-standardized. It includes

-   the icons
-   the internationalization strings
-   metadata about the app
-   frameworks and libraries, separated from the executable.

```bash
ls -1p "/Applications/Google Chrome.app/Contents/"

Frameworks/
Library/
Resources/
_CodeSignature/
MacOS/

Info.plist
PkgInfo
```

Such content should be treated as read-only, as tampering it triggers a signature change and security measures that prevent the executable from running.

The application's dynamic data and preferences are stored outside the bundle.

# Application's persisted data



The `Library` directory, located in the user's directory, helps to store data and preferences on behalf of applications.

While it has many directories, the ones that applications should use are as follows:

```
~/Library/Application\ Support/
~/Library/Caches
~/Library/Preferences
```

### preferences

The `Preferences` directory stores lightweight user-preferences files related to a given program. They represent persisted user-specific settings. For example, _com.apple.dock.plist_ stores the _Dock_ settings.

```bash
ls ~/Library/Preferences/

com.microsoft.VSCode.plist
com.blizzard.diablo3.plist
com.apple.dock.plist

plutil -p ~/Library/Preferences/com.apple.dock.plist
```

### application support

`Application Support` is the general purpose storage area where each application may persist arbitrary data, such as databases, downloaded content, or extensions.

### caches

`Caches` stores cached data on behalf of applications. Those are usually artifacts produced by network fetches, which cache the network responses to keep them available across runs.

# Launch processes automatically

### register a process for automatic launch

Applications (or simple processes) may request the OS to automatically launch them at boot-up or at user-login.

Boot-up items start before login, for critical services that should run as soon as possible and regardless of the user.

Login items start on user login, and may launch applications automatically.

### traditional registration process

We craft a `plist` file that identifies a process and provides some settings such as the launch arguments. We then place it in a hardcoded directory.

We place it in `/Library/LaunchDaemons` if it has to start on boot-up. We place it in either `/Library/LaunchAgents` or `~/Library/LaunchAgents` if it has to start on user login.

macOS manages a distinct database to keep track of which item has been disabled from the OS login-items settings.

```bash
open /Library/LaunchDaemons
open /Library/LaunchAgents
open ~/Library/LaunchAgents

sfltool dumpbtm

launchctl print-disabled user/$(id -u)
```

### modern registration process

applications are now encouraged to store the `plist` files inside their bundles and register them through a macOS API. This ends the pattern of having `plist` files outside of their bundles.

```
MyApp.app/
 └── Contents/
      ├── Info.plist
      ├── MacOS/
      │    └── MyApp  (The main executable)
      └── Library/
           └── LaunchAgents/
                └── com.myapp.helper.plist
```



# Default directories and files

### disk root directory

The root location aka `/` contains:

-   the UNIX-style directories aka `bin`, `usr`, and more. The `etc`, `tmp` and `var` directories are aliases: they live in `private/`.
-   the user-facing folders such as `Users`, `Applications`, `Library`, `System` and `Volumes`.

```
┌── Applications/
├── Library/
├── System/
├── Users/
├── Volumes/
│
├── bin/
├── cores/
├── dev/
├── etc/
├── home/
├── opt/
├── private/
├── sbin/
├── tmp/
├── usr/
└── var/
```

### user's root directory

The user's root directory, that we may refer to as `~`, contains:

```
┌── Desktop/
├── Documents/
├── Downloads/
├── Movies/
├── Music/
├── Pictures/
│
├── Public/
└── Library/
```

###


macOS

Customize an instance

Universal style props

Global customization

CSS Module pattern

Mantine's internal styling

Light mode, dark mode

Default theme

Gray Palette

Dark Palette

Global Style: Colors

Global style: Others

Flex

Group

Stack

SimpleGrid

Container

Center

Divider

Space

Paper

Accordion

Appshell

Tabs

Table data

Table with explicit structure

Table from data prop

TextInput

NumberInput

FileInput

Native Select

SegmentedControl

Button

Button.Group

ActionIcon

Pagination

Modal

Title

Text

Bar Chart

Progress

RingProgress

Avatar

Notifications

useForm

useLocalStorage

useDisclosure

useMantineColorTheme

# Overview

<div class="bookHeroImage" style="padding: 32px;margin: 8px 0;"><svg  xmlns="http://www.w3.org/2000/svg" viewBox="0 0 623 163" style="height:calc(2rem * var(--mantine-scale))" class="m_2075ec07"><g fill="none" fill-rule="evenodd"><path fill="#339af0" fill-rule="nonzero" d="M162.162 81.5c0-45.011-36.301-81.5-81.08-81.5C36.301 0 0 36.489 0 81.5 0 126.51 36.301 163 81.081 163s81.081-36.49 81.081-81.5z"></path><g fill="#fff"><path fill-rule="nonzero" d="M65.983 43.049a6.234 6.234 0 00-.336 6.884 6.14 6.14 0 001.618 1.786c9.444 7.036 14.866 17.794 14.866 29.52 0 11.726-5.422 22.484-14.866 29.52a6.142 6.142 0 00-1.616 1.786 6.211 6.211 0 00-.694 4.693c.197.79.546 1.533 1.028 2.186a6.154 6.154 0 008.634 1.284 50.112 50.112 0 007.947-7.39h17.493c3.406 0 6.174-2.772 6.174-6.194s-2.762-6.194-6.174-6.194h-9.655a49.166 49.166 0 004.071-19.69 49.166 49.166 0 00-4.07-19.692h9.66c3.406 0 6.173-2.771 6.173-6.194 0-3.422-2.762-6.193-6.173-6.193H82.574a50.11 50.11 0 00-7.952-7.397 6.149 6.149 0 00-4.578-1.153 6.189 6.189 0 00-4.055 2.438h-.006z"></path><path d="M56.236 79.391a9.342 9.342 0 01.632-3.608 9.261 9.261 0 011.967-3.077 9.143 9.143 0 012.994-2.063 9.06 9.06 0 017.103 0 9.144 9.144 0 012.995 2.063 9.261 9.261 0 011.967 3.077 9.34 9.34 0 01.63 3.608 9.299 9.299 0 01-2.755 6.395 9.094 9.094 0 01-6.388 2.63 9.094 9.094 0 01-6.39-2.63 9.299 9.299 0 01-2.755-6.395z"></path></g><path fill="currentColor" fill-rule="nonzero" d="M291.736 126.644c1.984 0 3.823-.434 5.518-1.302 1.695-.868 2.542-2.129 2.542-3.782v-77.5c0-2.976-.827-5.063-2.48-6.262-1.653-1.199-3.513-1.798-5.58-1.798-1.901 0-3.555.207-4.96.62-1.405.413-2.666 1.24-3.782 2.48s-2.418 3.059-3.906 5.456l-15.252 27.776-15.128-27.776c-1.323-2.397-2.583-4.216-3.782-5.456-1.199-1.24-2.48-2.067-3.844-2.48-1.364-.413-3.038-.62-5.022-.62-1.984 0-3.823.6-5.518 1.798-1.695 1.199-2.542 3.286-2.542 6.262v77.5c0 1.653.847 2.914 2.542 3.782 1.695.868 3.534 1.302 5.518 1.302 2.067 0 3.927-.434 5.58-1.302 1.653-.868 2.48-2.129 2.48-3.782V67.248l14.26 26.784c.744 1.24 1.591 2.087 2.542 2.542.95.455 1.88.682 2.79.682.992 0 1.984-.248 2.976-.744s1.86-1.323 2.604-2.48l14.384-25.792v53.32c0 1.653.847 2.914 2.542 3.782 1.695.868 3.534 1.302 5.518 1.302zm34.375 1.116c4.298 0 7.956-.992 10.974-2.976 3.017-1.984 5.642-4.257 7.874-6.82v3.596c0 1.405.682 2.604 2.046 3.596 1.364.992 3.08 1.488 5.146 1.488 2.232 0 4.092-.496 5.58-1.488 1.488-.992 2.232-2.19 2.232-3.596V91.18c0-4.216-.889-8.143-2.666-11.78-1.778-3.637-4.609-6.613-8.494-8.928-3.886-2.315-9.052-3.472-15.5-3.472-2.894 0-5.87.372-8.928 1.116-3.059.744-5.642 1.798-7.75 3.162-2.108 1.364-3.162 2.914-3.162 4.65 0 1.819.475 3.596 1.426 5.332.95 1.736 2.294 2.604 4.03 2.604 1.074 0 2.066-.33 2.976-.992.91-.661 2.211-1.302 3.906-1.922 1.694-.62 4.112-.93 7.254-.93 2.81 0 4.98.579 6.51 1.736 1.53 1.157 2.645 2.604 3.348 4.34a14.092 14.092 0 011.054 5.332v1.612h-5.084c-5.704 0-10.726.537-15.066 1.612-4.34 1.075-7.73 2.935-10.168 5.58-2.439 2.645-3.658 6.324-3.658 11.036 0 5.621 1.591 9.775 4.774 12.462 3.182 2.687 6.964 4.03 11.346 4.03zm6.448-11.904c-1.819 0-3.369-.537-4.65-1.612-1.282-1.075-1.922-2.77-1.922-5.084 0-2.315.764-4.03 2.294-5.146 1.53-1.116 3.534-1.84 6.014-2.17 2.48-.33 5.084-.496 7.812-.496h1.86v2.604c0 1.984-.6 3.885-1.798 5.704-1.199 1.819-2.666 3.307-4.402 4.464-1.736 1.157-3.472 1.736-5.208 1.736zm84.169 10.788c2.067 0 3.927-.434 5.58-1.302 1.653-.868 2.48-2.129 2.48-3.782V92.172c0-4.63-.971-8.845-2.914-12.648-1.943-3.803-4.526-6.84-7.75-9.114C410.9 68.137 407.345 67 403.46 67c-4.133 0-7.626.971-10.478 2.914-2.852 1.943-4.898 4.113-6.138 6.51v-3.72c0-1.488-.682-2.687-2.046-3.596-1.364-.91-3.038-1.364-5.022-1.364-2.315 0-4.216.455-5.704 1.364-1.488.91-2.232 2.108-2.232 3.596v48.856c0 1.24.744 2.397 2.232 3.472 1.488 1.075 3.39 1.612 5.704 1.612 2.232 0 4.133-.537 5.704-1.612 1.57-1.075 2.356-2.232 2.356-3.472V92.172c0-2.315.496-4.299 1.488-5.952.992-1.653 2.273-2.935 3.844-3.844 1.57-.91 3.183-1.364 4.836-1.364 1.984 0 3.803.558 5.456 1.674 1.653 1.116 2.955 2.5 3.906 4.154a10.52 10.52 0 011.426 5.332v29.388c0 1.653.868 2.914 2.604 3.782 1.736.868 3.513 1.302 5.332 1.302zm47.432 0c2.315 0 4.03-.703 5.146-2.108 1.116-1.405 1.674-2.976 1.674-4.712 0-1.653-.558-3.183-1.674-4.588-1.116-1.405-2.831-2.108-5.146-2.108h-4.836c-2.563 0-4.36-.496-5.394-1.488-1.033-.992-1.55-2.687-1.55-5.084V79.4h14.632c1.323 0 2.335-.6 3.038-1.798.703-1.199 1.054-2.542 1.054-4.03 0-1.488-.351-2.831-1.054-4.03-.703-1.199-1.715-1.798-3.038-1.798H452.38V46.416c0-1.488-.847-2.687-2.542-3.596-1.695-.91-3.534-1.364-5.518-1.364-1.819 0-3.596.455-5.332 1.364-1.736.91-2.604 2.108-2.604 3.596v60.14c0 6.944 1.963 12.028 5.89 15.252 3.927 3.224 9.61 4.836 17.05 4.836h4.836zM487.232 54.6c2.397 0 4.443-.806 6.138-2.418 1.695-1.612 2.542-3.41 2.542-5.394 0-2.15-.847-3.989-2.542-5.518-1.695-1.53-3.74-2.294-6.138-2.294-2.397 0-4.464.765-6.2 2.294-1.736 1.53-2.604 3.369-2.604 5.518 0 1.984.868 3.782 2.604 5.394 1.736 1.612 3.803 2.418 6.2 2.418zm0 72.044c2.232 0 4.133-.537 5.704-1.612 1.57-1.075 2.356-2.232 2.356-3.472V72.704c0-1.488-.785-2.687-2.356-3.596-1.57-.91-3.472-1.364-5.704-1.364-2.315 0-4.216.455-5.704 1.364-1.488.91-2.232 2.108-2.232 3.596v48.856c0 1.24.744 2.397 2.232 3.472 1.488 1.075 3.39 1.612 5.704 1.612zm65.247 0c2.066 0 3.926-.434 5.58-1.302 1.653-.868 2.48-2.129 2.48-3.782V92.172c0-4.63-.972-8.845-2.914-12.648-1.943-3.803-4.526-6.84-7.75-9.114-3.224-2.273-6.779-3.41-10.664-3.41-4.134 0-7.626.971-10.478 2.914-2.852 1.943-4.898 4.113-6.138 6.51v-3.72c0-1.488-.682-2.687-2.046-3.596-1.364-.91-3.038-1.364-5.022-1.364-2.315 0-4.216.455-5.704 1.364-1.488.91-2.232 2.108-2.232 3.596v48.856c0 1.24.744 2.397 2.232 3.472 1.488 1.075 3.39 1.612 5.704 1.612 2.232 0 4.133-.537 5.704-1.612 1.57-1.075 2.356-2.232 2.356-3.472V92.172c0-2.315.496-4.299 1.488-5.952.992-1.653 2.273-2.935 3.844-3.844 1.57-.91 3.182-1.364 4.836-1.364 1.984 0 3.802.558 5.456 1.674 1.653 1.116 2.955 2.5 3.906 4.154a10.52 10.52 0 011.426 5.332v29.388c0 1.653.868 2.914 2.604 3.782 1.736.868 3.513 1.302 5.332 1.302zm47.68 1.116c4.464 0 8.328-.558 11.594-1.674 3.265-1.116 5.786-2.48 7.564-4.092 1.777-1.612 2.666-3.12 2.666-4.526 0-.827-.248-1.798-.744-2.914a8.641 8.641 0 00-2.108-2.914c-.91-.827-1.984-1.24-3.224-1.24-1.158 0-2.398.372-3.72 1.116-1.323.744-2.894 1.53-4.712 2.356-1.819.827-4.092 1.24-6.82 1.24-4.299 0-7.792-1.095-10.478-3.286-2.687-2.19-4.03-5.063-4.03-8.618v-1.86h25.172c1.901 0 3.74-.186 5.518-.558 1.777-.372 3.244-1.323 4.402-2.852 1.157-1.53 1.736-4.071 1.736-7.626 0-4.63-1.199-8.68-3.596-12.152-2.398-3.472-5.518-6.2-9.362-8.184-3.844-1.984-8.08-2.976-12.71-2.976-5.043 0-9.61 1.137-13.702 3.41-4.092 2.273-7.358 5.29-9.796 9.052-2.439 3.761-3.658 7.874-3.658 12.338v10.54c0 5.043 1.281 9.486 3.844 13.33 2.562 3.844 6.096 6.82 10.602 8.928 4.505 2.108 9.692 3.162 15.562 3.162zm4.092-35.836h-18.104v-3.472c0-1.984.516-3.7 1.55-5.146 1.033-1.447 2.376-2.563 4.03-3.348 1.653-.785 3.43-1.178 5.332-1.178 1.984 0 3.802.413 5.456 1.24 1.653.827 2.976 1.984 3.968 3.472s1.488 3.183 1.488 5.084c0 1.323-.269 2.211-.806 2.666-.538.455-1.509.682-2.914.682z"></path></g></svg></div>

[Mantine](https://mantine.dev/) provides an infrastructure to build React apps efficiently, with pre-styled UI components and feature-rich utilities.

### benefits

-   solid UI defaults: neutral, minimalist, functional style.
-   easy-to-use, consistent API (DX)
-   rapid development of utilitarian and productivity apps

### mantine style is opinionated and cohesive

Mantine brings a set of cohesive style defaults.

If we aim to override some style, we should make it compatible with the Mantine overall look.

Some components, such as layout components and Mantine hooks, don't have a visible style, so we may use them in any design or project.

### mantine's packages

Mantine provides distinct packages. The main ones are Mantine _core_ and Mantine _hooks_.

-   [core components source-code](https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/core/src/components)
-   [hooks source-code](https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/hooks/src)

### terminology: components and component variants

Mantine provides components, and for some of them, _variants_. For example,
it provides the _Button_ component, for which it provides the _outline_ and _filled_ variants.

### terminology: component's inner-elements

A component is constructed through several, named, _inner-elements_.
For example, _Slider_ is built upon a _mark_, a _track_ and a _bar_. We may style the inner-elements distinctively.

### customization patterns

We have three main patterns:

-   (Local) customization of an instance: the scope of the change is local and limited.
-   (Global) override of a Mantine component: it affects all sites that use these components.
-   (Global) customization of style primitives, also called theming, which affects several components.



# Customize an instance



### overview

We want to customize a single instance of a component.

We do that by adding inline style, classes, or provide props.

### inner workings

Technically, this pattern resolves to:

-   style that lives in the element's _style_ attribute
-   markers set on the element, such as a class, an id, an attribute or a custom attribute, along with some CSS targeting those markers.
-   inner DOM elements being added.

### the limits of setting style or className attributes directly

We may provide quick inline style in the _style_ attribute or classes to the _className_ attribute, but there is no granularity into which inner-element we target. The style we provide usually applies to the root inner-element.

While this is possible, it's not a pattern recommended by Mantine, because it doesn't let Mantine act as an intermediary.

### mantine patterns

Mantine offers patterns that are more powerful, and for them, allow to target inner-elements.

### props that we may set on any Mantine component instance.

Mantine's `style props` are a set of props that we may set on any Mantine component, and which aim to set a single style aspect. The style targets the top-level element.

```tsx
<Box m={4}></Box>
```

### props that are specific to one or more components

Some props are unique to some components. They may determine the style, but also determine the component's inner structure, such as toggling inner-elements. For example, the TextInput's _label_ prop adds a _label_ element in addition to the _input_ element.

```tsx
<TextInput label="Username"></TextInput>
// adds:
<label>Username</label>
```

### target an inner-element

We target an inner-element by specifying its Mantine-defined name, and provide a style object (_styles_ pattern) or one or more classes (_classNames_ pattern).

```tsx
 <Button
	styles={{
        root: { backgroundColor: 'red', height: 16},
        label: { color: 'blue' },
      }}
```

```tsx
<Button
    classNames={{
        root: "primarybutton-root",
        label: "primarybutton-label",
    }}
/>
```

### class naming pattern

The classes we provide in _styles_ are to customize an instance of a given Mantine component. But we may wrap the instance into a new component, effectively creating a variant of the given Mantine component.

Given that, we may use the variant's name in all classes related to it, as a prefix, such as _pinkbutton_-\* if we are making a Button variant. if we are to target an inner component, we use its name as a suffix.

```txt
.pinkbutton-root
.pinkbutton-label
```

# Universal style props



Mantine components accept a series of props that let us control various style aspects:

### spacing

| Prop   | CSS Property              | Theme key     |
| :----- | ------------------------- | ------------- |
| **m**  | margin                    | theme.spacing |
| **mt** | marginTop                 | theme.spacing |
| **mb** | marginBottom              | theme.spacing |
| **ml** | marginLeft                | theme.spacing |
| **mr** | marginRight               | theme.spacing |
| **mx** | marginRight, marginLeft   | theme.spacing |
| **my** | marginTop, marginBottom   | theme.spacing |
|        |                           |               |
| **p**  | padding                   | theme.spacing |
| **pt** | paddingTop                | theme.spacing |
| **pb** | paddingBottom             | theme.spacing |
| **pl** | paddingLeft               | theme.spacing |
| **pr** | paddingRight              | theme.spacing |
| **px** | paddingRight, paddingLeft | theme.spacing |
| **py** | paddingTop, paddingBottom | theme.spacing |

### typography

| Prop    | CSS Property   | Theme key         |
| :------ | -------------- | ----------------- |
| **ff**  | fontFamily     | –                 |
| **fz**  | fontSize       | theme.fontSizes   |
| **fw**  | fontWeight     | –                 |
| **lts** | letterSpacing  | –                 |
| **ta**  | textAlign      | –                 |
| **lh**  | lineHeight     | theme.lineHeights |
| **fs**  | fontStyle      | –                 |
| **tt**  | textTransform  | –                 |
| **td**  | textDecoration | –                 |

### size

| Prop    | CSS Property | Theme key     |
| :------ | ------------ | ------------- |
| **w**   | width        | theme.spacing |
| **miw** | minWidth     | theme.spacing |
| **maw** | maxWidth     | theme.spacing |
| **h**   | height       | theme.spacing |
| **mih** | minHeight    | theme.spacing |
| **mah** | maxHeight    | theme.spacing |

### position

| Prop       | CSS Property | Theme key |
| :--------- | ------------ | --------- |
| **pos**    | position     | –         |
| **top**    | top          | –         |
| **left**   | left         | –         |
| **bottom** | bottom       | –         |
| **right**  | right        | –         |
| **inset**  | inset        | –         |

### other props

| Prop        | CSS Property         | Theme key                |
| :---------- | -------------------- | ------------------------ |
| **display** | display              | –                        |
|             |                      |                          |
| **flex**    | flex                 |                          |
|             |                      |                          |
| **bd**      | border               |                          |
| **bdrs**    | borderRadius         |                          |
|             |                      |                          |
| **bg**      | background           | theme.colors             |
| **bgsz**    | backgroundSize       | –                        |
| **bgp**     | backgroundPosition   | –                        |
| **bgr**     | backgroundRepeat     | –                        |
| **bga**     | backgroundAttachment | –                        |
|             |                      |                          |
| **c**       | color                | theme.colors gray.5 blue |
| **opacity** | opacity              | –                        |

### responsiveness: provide alternative values.

Instead of a single value, we provide an object with alternative values. Most of
the time, we only provide two values.

-   the _base_ value provides the mobile-centric, default value. Its exact scope depends on which other breakpoints we define.
-   The _xs_ value activates at 576p. It excludes most smartphones. For reference, iPhones are under 450p width, with standard-size iPhones under 400p. If we want to exclude phablets as well, we use _sm_ instead.
-   The _sm_ value activates at 768p (48em), which excludes phablets, and includes tablets and wider screens. For reference, iPads start at 768px.

```tsx
<Flex
 direction=	{{ base: 'column',sm: 'row' }}
 gap=		{{ base: 'sm', 	sm: 'lg' }}
 justify=	{{ base: 'sm', 	sm: 'lg' }}
>
```

# Global customization



Global customization, also called theming, aims to override some style-primitives to affect several components, or, with a smaller reach, to override a component to affect all instances.

### customize style primitives

#todo

### implement Mantine-provided, component-scoped empty classes

Mantine sticks a series of empty classes on each of its built-in components. We may implement them to customize a given aspect of a given component.

(Implementing such class affects all instances)

For example, Mantine sticks `mantine-Button-root` and `mantine-Button-label` on inner-elements of the _Button_ component.

```css
.mantine-Button-root {
    border-width: 0.5px;
}
```

### empty classes specificity

Those classes have the same specificity than Mantine's implemented internal classes. One technique to make them win is to import our stylesheet after Mantine's one.

# CSS Module pattern



### css module pattern overview

A processor parses a given stylesheet to scan the classes and expose them to JS. It generates a globally unique name for each of them. It packs the developer-defined classes and globally unique classes in a dictionary object:

```tsx
export const classes = {
    supercool: "supercool_5cEkq2n0x1",
    supernice: "supernice_1kmox6oL39",
    superGreat: "superGreat_1kmox6oL39",
    "super-awesome": "super-awesome_1kmox6oL39",
} // conceptual // class dictionary
```

We import the dictionary.

```tsx
import classes from "xxx.module.css";

<Button
classNames={{
        root: classes.xxx, 	// resolves to the processed class
        label: classes.xxx,	// resolves to the processed class
    }}
  >
```

### pattern: a module targets a Mantine component custom variant

In this pattern, the module's purpose is to define the style of a Mantine component custom variant for which we create a name. For example, we may create a _PrimaryButton_ variant of `Button`. We name the CSS Module with the variant name: `PrimaryButton.module.css`

We name the classes according to the inner-element they target, such as _root_ or _label_.

```css
/* PrimaryButton.module.css */
.root {
}

.root:hover {
}

.label {
}
```

We may then use the classes to inline-customize a Mantine's component instance, or to create a fully-fledged React component variant.

```tsx
import PrimaryButtonClassNames from "PrimaryButton.module.css";
{/* provide properties */}
<Button
classNames={{
        root: PrimaryButtonClassNames.root,
        label: PrimaryButtonClassNames.label,
    }}
  >
```

### provide the classes object directly

When we follow the inner-element-as-a-classname naming pattern, we may give the CSS-module object directly to `classNames`, since _classNames_ expects an object with inner-element named properties.

```tsx
<Button classNames={primaryButtonClassNames}>
```

# Mantine's internal styling



### case study: Mantine's implementation of Button

The [Button source code](https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/core/src/components/Button) includes the typescript file (`Button.tsx`) and the stylesheet (`Button.module.css`).

### HTML element structure

There are several, nested elements:

-   the _root_ button is the top level container.
-   the _inner_ span is an intermediate container for the _label_ and the _sections_
-   a _section_ is a container for an icon.
-   the _label_ span contains the button's text.
-   the _loader_ span is an intermediate container for a loader.

```tsx
/* root */
<button>
    {/* 1.0 loader container*/}
    <span />
    {/* 2.0 inner */}
    <span>
        {/* 2.1 section  */}
        <span>
            <svg /> {/* 2.1.0 icon */}
        </span>
        {/* 2.2 label  */}
        <span>{/* 2.2.0 text */}</span>
    </span>
</button>
```

Both the mantine-implemented internal classes and empty classes are present, on each inner-element:

```tsx
<button class="m-77c9d27d mantine-Button-root .." ..>
    <span class="m-80f1301b mantine-Button-inner">
        <span class="m-811560b9 mantine-Button-label">
          Save
      </span>
    </span>
</button>
```

some inner-elements have some data-attributes, which may be shared across inner-elements of distinct components, such as the _mantine-active_ and _mantine-focus-auto_ attributes.

For example, `mantine-active` allows to receive style that activates when the element is active. The attribute is always there, and the stylesheet discriminates to the :active state.

```css
mantine-active:active {
    transform: translateY(calc(0.0625rem));
}
```

### Button's stylesheet

The [stylesheet](https://github.com/mantinedev/mantine/blob/master/packages/%40mantine/core/src/components/Button/Button.module.css) is a CSS module and follows the pattern where classes are named after inner-elements of the Button component. We reproduce parts of the _root_ class.

The [.tsx file](https://github.com/mantinedev/mantine/blob/master/packages/%40mantine/core/src/components/Button/Button.tsx) imports the CSS module.

### style shipped on npm

the style is mostly the same. It is probably processed by PostCSS. It does not use CSS nesting.

It is then processed even more and merged to a gigantic 232kb stylesheet, shipped on npm too, the one we import from our app.

# Light mode, dark mode



Mantine defaults to light mode: `defaultColorScheme` defaults to `light`.

```We may change it to `dark`or`auto`. `auto` is better because it follows the user's color scheme.

```tsx
<MantineProvider defaultColorScheme="auto"></MantineProvider>
```

# Default theme



The [default theme](https://v7.mantine.dev/theming/default-theme/) spreads over several categories.

### spacing

space between elements and inside elements.

```tsx
xs: 10px
sm: 12px
md: 16px
lg: 20px
xl: 32px
```

used for or usable by:

-   gap for Group, Flex, Stack.
-   padding props.
-   margin props, notably for Divider
-   width and height props such as `w` and `h`, notably for Space.

### radius

```tsx
xs: 2px
sm: 4px (d)
md: 8px
lg: 16px
xl: 32px
```

used for:

-   Paper
-   Dialog, Modal, ..
-   Button, Tooltip..

we may set the default with _defaultRadius_:

```tsx
"defaultRadius": "sm",
```

### breakpoints

a set of alternative thresholds that we may target to activate style conditionally.

```tsx
  "breakpoints": {
    "xs": "36em", // 576px
    "sm": "48em", // 768px
    "md": "62em",
    "lg": "75em",
    "xl": "88em"
  },
```

The `sm` breakpoint targets tablets and wider devices.

we specify one or more thresholds in the styles-props alternative-values pattern.

### font sizes: a set of 5 distinct sizes

```tsx
"fontSizes": {
    "xs": 12px
    "sm": 14px
    "md": 16px,
    "lg": 18px
    "xl": 20px
  },
```

Those sizes do not affect headings. We may use them in:

-   the _fz_ style prop, on any component.

### line heights

```ts
  "lineHeights": {
    xs: 1.4,
    sm: 1.45,
    md: 1.55,
    lg: 1.6,
    xl: 1.65
  },
```

### headings

family, weight and wrap behavior:

```tsx
"headings": {
    "fontFamily": "-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji",
    "fontWeight": "700",
    "textWrap": "wrap",
  },
```

size and line height:

```ts
  "sizes": {
      "h1": {
        "fontSize": "calc(2.125rem * var(--mantine-scale))",
        "lineHeight": "1.3"
      },
      "h2": {
        "fontSize": "calc(1.625rem * var(--mantine-scale))",
        "lineHeight": "1.35"
      },
      "h3": {
        "fontSize": "calc(1.375rem * var(--mantine-scale))",
        "lineHeight": "1.4"
      },
      "h4": {
        "fontSize": "calc(1.125rem * var(--mantine-scale))",
        "lineHeight": "1.45"
      },
      "h5": {
        "fontSize": "calc(1rem * var(--mantine-scale))",
        "lineHeight": "1.5"
      },
      "h6": {
        "fontSize": "calc(0.875rem * var(--mantine-scale))",
        "lineHeight": "1.5"
      }
    }
```

# Gray Palette



### description and use

It is a slate gray: it has a blue tint.

Mantine's `light-mode` theme makes use of this palette: it offers several whites for backgrounds, and a few dark grays for text. It does not include pure white, instead, it starts at #F8F9FA.

The following consideration usually apply for light-mode:

-   The background may be pure white. It may be the app/site global background of the controls background.

-   The background may go darker on hover. This is the case for buttons, and for the select's options: `gray.1`

-   The text is black-ish or gray-ish depending on importance and role:
    -   pure black text:
        -   some headings
        -   body text
        -   input label
        -   button label
    -   gray 9 (readable black for body text)
    -   gray 8 (readable black)
    -   dark 7 (dimmed black)
    -   gray 6 (gray) for secondary text, and input description

### values

-   `gray.0` white: #F8F9FA
-   `gray.1` white: #F1F3F5
-   `gray.2` white gray: #E9ECEF
-   ...
-   `gray.6` gray: #868e96
-   `gray.7` dark gray: #495057
-   `gray.8` very dark gray: #343A40
-   `gray.9`: very dark gray: #212529

# Dark Palette



### the dark palette

It is a neutral gray palette. It was a slate-gray palette (blue-tint) before Mantine 7.3.

Mantine's `dark-mode` theme makes use of this palette. It offers several darks for backgrounds, grays for controls, and whites for text.

### use in dark mode

-   The app background is dark 7. We may go darker with dark 8.
-   Controls have lighter backgrounds: dark 6, and even lighter on hover: dark 5.
    Sometimes, hover goes to a darker background instead: such as the hovered option in a select control: dark 8.
-   The text is light. It uses one of those colors:
    -   pure white (bright white for some headings)
    -   dark 0 (readable white for body text)
    -   dark 1 (slightly dimmed)
    -   dark 2 (dimmed, secondary text, matches `c=dimmed`)
-   The button label is pure white, both for _filled_ and _default_ variants.
-   The input's label is dark 0, the input's description is dark 2.
-   The dimmed text is dark 2, such as secondary label, or secondary
    text in general.

### values

-   `dark.0`: very light gray close to white: #C9C9C9.
-   ..
-   `dark.9`: black: #141414

### revert to blue-tinted dark palette

```tsx
const theme = createTheme({
    colors: {
        dark: [
            "#C1C2C5",
            "#A6A7AB",
            "#909296",
            "#5c5f66",
            "#373A40",
            "#2C2E33",
            "#25262b",
            "#1A1B1E",
            "#141517",
            "#101113",
        ],
    },
})
```

# Global Style: Colors



#todo

```css
--mantine-color-scheme: dark;
--mantine-primary-color-contrast: var(--mantine-color-white);
--mantine-color-bright: var(--mantine-color-white);
--mantine-color-text: var(--mantine-color-dark-0);
--mantine-color-body: var(--mantine-color-dark-7);
--mantine-color-error: var(--mantine-color-red-8);
--mantine-color-placeholder: var(--mantine-color-dark-3);
--mantine-color-anchor: var(--mantine-color-blue-4);
--mantine-color-default: var(--mantine-color-dark-6);
--mantine-color-default-hover: var(--mantine-color-dark-5);
--mantine-color-default-color: var(--mantine-color-white);
--mantine-color-default-border: var(--mantine-color-dark-4);
--mantine-color-dimmed: var(--mantine-color-dark-2);
--mantine-color-dark-text: var(--mantine-color-dark-4);
--mantine-color-dark-filled: var(--mantine-color-dark-8);
--mantine-color-dark-filled-hover: var(--mantine-color-dark-7);
--mantine-color-dark-light: rgba(36, 36, 36, 0.15);
--mantine-color-dark-light-hover: rgba(36, 36, 36, 0.2);
--mantine-color-dark-light-color: var(--mantine-color-dark-3);
--mantine-color-dark-outline: var(--mantine-color-dark-4);
--mantine-color-dark-outline-hover: rgba(36, 36, 36, 0.05);
--mantine-color-gray-text: var(--mantine-color-gray-4);
--mantine-color-gray-filled: var(--mantine-color-gray-8);
--mantine-color-gray-filled-hover: var(--mantine-color-gray-9);
--mantine-color-gray-light: rgba(134, 142, 150, 0.15);
--mantine-color-gray-light-hover: rgba(134, 142, 150, 0.2);
--mantine-color-gray-light-color: var(--mantine-color-gray-3);
--mantine-color-gray-outline: var(--mantine-color-gray-4);
--mantine-color-gray-outline-hover: rgba(206, 212, 218, 0.05);
--mantine-color-red-text: var(--mantine-color-red-4);
```

# Global style: Others



line-height defaults to 1.55

```css
--mantine-line-height: 1.55;
```

# Flex



Use a bare-bones flex container, with nothing set except _display: flex_.

### override CSS defaults

-   Switch the `direction`, which is horizontal (_row_) by default, to vertical (_column_). It's best to switch conditionally.
-   Increase the `gap` (defaults to 0)
-   Control `justify`, aka main axis alignment, which default to _flex-start_.
-   Control `align`, aka cross-axis alignment, which defaults to _stretch_.

Example of a responsive flex container:

```tsx
<Flex
    direction={{ base: "column", sm: "row" }}
    gap={{ base: "sm", sm: "lg" }}
    justify={{ base: "flex-start", sm: "space-between" }}
/>
```

# Group



Layout elements horizontally and add space between them. The container spans the whole line. It uses a horizontal flex under the hood.

The differences with a stock horizontal flex:

-   It adds some `gap` between elements (defaults to _md_, aka 16px).
-   It centers elements vertically, with `align`, instead of stretching them.
-   It wraps when needed (multi-line flex) (set `wrap` to either mono-line (_nowrap_) or multi-line (_wrap_), which sets the underlying _flex-wrap_ property).

### overrides

-   Make children fill the container with `grow`.

    -   It sets _flex-grow: 1_ on children.
    -   By default, it makes them same-width (by capping them to a _max-width_) and put them on a single line (because it caps children to a share of the line).
    -   We can reestablish multi-line by turning off `preventGrowOverflow` which turns off capping. _wrapping_ was never disabled in this scenario.
    -   If we also add _nowrap_, it's back a mono-line flex where children grow proportionally to their _flex-basis_ (It's convoluted)

-   (non-Group specific) Pick horizontal alignment with `justify`. It defaults to _flex-start_ like stock flexes.

# Stack



Layout elements vertically and add space between them.

The container spans the whole line (because its _width_ is still _auto_). It uses a vertical flex under the hood. Items default to spread horizontally within it.

Differences with a stock vertical flex:

-   It adds a `gap` (16px by default).

Other settings to override CSS default values:

-   `justify`: elements sit at the top by default (_flex-start_)
-   `align`: elements fill the stack horizontally by default (_stretch_)

# SimpleGrid



Set up a column layout with a given number of equal-width columns.

The grid container spans the whole line and the columns together span the whole container.

The grid container adds space between tracks by default (_16px_) (both horizontal and vertical spacing aka `spacing` and `verticalSpacing`).

We set the number of columns with `cols`. It defaults to a single track. Best Practice: adapt the column count based on screen size, by providing at least two values.

```tsx
<SimpleGrid cols={3}>
  {/* items */}
</SimpleGrid>

<SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }}>
  {/* items */}
</SimpleGrid>
```

# Container



A wrapper that centers the content and keeps it aways from the screen edges. For example, we wrap the main column of a website, to have centering in desktop and padding on mobile.

### max-width version

The default version comes with a max-width (for desktop) and some padding (for mobiles). It centers the content with _margin: auto_.

The max-width defaults to _md_ (aka 960px). We change it with `size`. For example, we can pick
720px (_sm_) instead. If we are to provide an arbitrary numeric value, we may as well set `maw` directly to remove indirection.

The default padding is 16px, aka _md_. We change it with the regular `px` style prop.

### fluid version

We may opt for a fluid container, which expands horizontally, with the `fluid` prop. It only comes with some padding, at 16px. A _Box_ with horizontal padding has the same effect.

### grid version

The grid version doesn't use padding and doesn't center with _max-width_. Instead, it sets a grid layout and center stuff with grid positioning.

# Center



Center the child or the group of children horizontally and vertically.

Under the hood, it uses a flex container that justify and align the group of children to the center.

### vertical-centering and height

Vertical centering will only come into play if _Center_'s height is bigger than the inner content.

### horizontal-centering and width.

The container flex spreads horizontally (width: auto), but compacts its children to `max-content`. We can prevent compaction by setting the group of children to _width: 100%_.

# Divider



Separate items or sections with a visible line, similar in essence to the \<hr\> element.

Under the hood, it is an empty element whose border acts as the visible line.

-   The line is horizontal by default, we can set it to vertical with `orientation`.
-   We set the line thickness with `size`. It defaults to 1px.
-   The line is solid by default. We switch to _dashed_ or _dotted_ with `variant`.
-   The line doesn't add margin around itself by default. We add margin with _my_ or _mx_.
-   The line's color defaults to:
    -   `--mantine-color-dark-4: #424242;` in dark mode (dark gray)
    -   `--mantine-color-gray-3: #dee2e6;` in light mode (light gray)

# Space



Separate items with some white space. Mantine uses an empty element with some explicit size. It defaults to a zero size. We set the height or the width:

-   Set vertical spacing with `h`, usually in a stack-like layout.
-   Set horizontal spacing with `w`, usually in a horizontal flex-like layout.

# Paper



Encapsulate some UI to set it apart visually.

The Paper's default background is the same as the *body*'s default background (*--mantine-color-body*).

-   In light mode, it is white \#FFF.
-   In dark mode, it is _dark.7_.

We can override's Paper background with `bg`.

Paper also adds a `radius` (*theme.defaultRadius*) which defaults to 4px.

### Paper specific customizations

-   Add a pre-styled border with `withBorder` (boolean)
-   Add a pre-styled shadow with `shadow`. We specify a named size (e.g. _sm_), or a *box-shadow* CSS literal.

# Accordion



Establish one or more expandable items that disclose more content when interacted with.

### item: show a preview and enable disclosure of a panel

The Accordion contains one or several items. An item
starts as a clickable preview (_Accordion.Control_) and embeds a
panel, that starts as hidden, and that is toggled on click.

Mantine mounts all panels immediately, regardless of their toggle state. The panel may be a form. In that case, we can set the chevron as a plus sign, to signal we add some data.

We set the chevron style at the Accordion root element's level, since all items use it.

```tsx
<Accordion variant="separated" chevron={<IconPlus/>}>
	<Accordion.Item value="item1">
		<Accordion.Control>
			Log Workout
      </Accordion.Control>
		<Accordion.Panel>
			Content
      </Accordion.Panel>
    </Accordion.Item>
 </Accordion>
```

### items appearance

By default, items are separated by a thin line. We can set `variant` to *separated* instead, or other [variants](https://mantine.dev/core/accordion/).

# Appshell



Appshell is a mega layout component that manages:

-   The _header_ on-top of the page, also called the banner.
-   The _main_ section, below the header
-   The left-side _navbar_ and the right-side _aside_ (if applicable)

### header: Appshell.Header

The header manages:

-   the burger button
-   the logo
-   the dark mode / light mode toggle (potentially)
-   the user button (potentially)
-   a set of links (potentially)

### configure the header

We build a header config and provide it to AppShell as a _header_ prop. We commonly set the _height_.

```tsx
<AppShell /* ... */ header={{ height: 60 }} />
```

### navbar: Appshell.Navbar

The _navbar_ stands on the left side. It is transient on mobile devices. On desktop it is commonly always-on, but Mantine supports having a conditional collapse as well, following a distinct logic and state variable.

We build a navbar config and provide it to AppShell as a _navbar_ prop. _collapsed_ aims to control the display of the navbar, while _breakpoint_ sets the breakpoint from which we go from _mobile_ to _desktop_ logic.

```tsx
<AppShell /* ... */ navbar={{}} />
```

-   `collapsed` receives up to two boolean state variables: one for _mobile_ and one for _desktop_. Most of the time, we only set _mobile_.
-   `breakpoint` controls when the collapse logic switches from mobile to desktop, aka when to use the mobile opened state versus the desktop opened state.
-   The burger button is responsible for toggling the state on and off. We hide the mobile burger button with `hiddenFrom`. If desktop supports collapse too, we use a distinct burger button (see below).

```tsx
const [mobileOpened, { toggle: toggleMobile }] = useDisclosure()

return (
    <AppShell
        navbar={{
            collapsed: { mobile: !opened },
            breakpoint: "sm",
        }}
    >
        <AppShell.Header>
            <Burger opened={opened} onClick={toggle} hiddenFrom="sm" />
        </AppShell.Header>
    </AppShell>
)
```

### navbar: allow collapse on desktop

We may allow the collapse behavior on Desktop as well: we create an additional, distinct boolean state variable, and provide it to the _desktop_ property of `collapsed`. We also add a dedicated desktop burger button, which commonly keeps the same appearance regardless of the collapse state (we don't show a close icon because there is no overlay). This burger button limits its display to desktop with _visibleFrom_.

```tsx
const [mobileOpened, { toggle: toggleMobile }] = useDisclosure(false)
const [desktopOpened, { toggle: toggleDesktop }] = useDisclosure(true)

return (
    <AppShell
        navbar={{
            collapsed: { mobile: !mobileOpened, desktop: !desktopOpened },
            breakpoint: "sm",
        }}
    >
        <AppShell.Header>
            {/* mobile */}
            <Burger opened={mobileOpened} onClick={toggleMobile} hiddenFrom="sm" />
            {/* desktop */}
            <Burger opened={false} onClick={toggleDesktop} visibleFrom="sm" />
        </AppShell.Header>
    </AppShell>
)
```

### navbar: other configuration

```tsx
navbar={{ width: 300, /* ... */ }}
```

-   `width` controls the width in desktop mode (it is always full-screen in mobile). We provide an immediate value or an object with two or more values.

### navbar: implement top and bottom sections

We may split the navbar into _AppShell.Sections_, and one of them may grow.

```tsx
<AppShell.Navbar>
    <AppShell.Section grow> </AppShell.Section>
    <AppShell.Section> </AppShell.Section>
</AppShell.Navbar>
```

### Appshell.Main

The container for the main panel.

We may set the panel background color. The default light theme sets a _white_ background while the dark theme sets a _dark.7_ background.

Override example: we may pick a light gray background such as _gray.1_, so that inner containers may stand out as white. Similarly, we may change the background to _dark.8_ so that inner elements may standout as _dark.7_.

```tsx
const backgroundColor = colorScheme === "dark" ? "dark.8" : "gray.1"
```

### synopsis

the configuration objects are required if we use the matching element, except for _main_ which may not be configured with this pattern.

```tsx
<AppShell header={{}} navbar={{}} aside={{}} footer={{}}>
    <AppShell.Header />
    <AppShell.Navbar />
    <AppShell.Aside />
    <AppShell.Main />
    <AppShell.Footer />
</AppShell>
```

# Table data



### abstract

A table works with an array of items, where each item is a row, and each property or member is a cell.

An item may come as an object or as an array.

### pattern: the item is an object

```ts
const items = [
    { position: 6, mass: 12.011, symbol: "C", name: "Carbon" },
    { position: 7, mass: 14.007, symbol: "N", name: "Nitrogen" },
    { position: 39, mass: 88.906, symbol: "Y", name: "Yttrium" },
    { position: 56, mass: 137.33, symbol: "Ba", name: "Barium" },
    { position: 58, mass: 140.12, symbol: "Ce", name: "Cerium" },
]
```

### pattern: the item is an array

```ts
const items = [
    [6, 12.011, "C", "Carbon"],
    [7, 14.007, "N", "Nitrogen"],
    [39, 88.906, "Y", "Yttrium"],
    [56, 137.33, "Ba", "Barium"],
    [58, 140.12, "Ce", "Cerium"],
]
```

We may come with this data by transforming an array of objects to an array of arrays:

```ts
const items = players.map((p) => [p.name, p.level, p.class])
```

### headers

An array usually comes with headers. We may provide them in an array.

```ts
const headers = ["Element position", "Atomic mass", "Symbol", "Element name"]
```

# Table with explicit structure



### structure preview

```tsx
<Table>
    <Table.Thead>
        {/* head */}
        <Table.Tr>
            <Table.Th>{col1Label}</Table.Th>
            <Table.Th>{col2Label}</Table.Th>
            <Table.Th>{col3Label}</Table.Th>
        </Table.Tr>
    </Table.Thead>

    {/* body */}
    <Table.Tbody>
        <Table.Tr>
            <Table.Td>{item1.name}</Table.Td>
            <Table.Td>{item1.level}</Table.Td>
            <Table.Td>{item1.class}</Table.Td>
        </Table.Tr>
        {/* ... more rows */}
    </Table.Tbody>
</Table>
```

### build rows from an array of objects

```tsx
const rows = items.map((item) => (
    <Table.Tr>
        <Table.Td>{item.name}</Table.Td>
        <Table.Td>{item.level}</Table.Td>
        <Table.Td>{item.class}</Table.Td>
    </Table.Tr>
))
```

### build rows from an array of arrays

```tsx
const rows = items.map((item) => (
    <Table.Tr>
        <Table.Td>{item[0]}</Table.Td>
        <Table.Td>{item[1]}</Table.Td>
        <Table.Td>{item[2]}</Table.Td>
    </Table.Tr>
))
```

### headers and body

_Thead_ is the container for the headers.

```tsx
<Table.Thead>
    <Table.Tr>
        <Table.Th>{col1Label}</Table.Th>
        <Table.Th>{col2Label}</Table.Th>
        <Table.Th>{col3Label}</Table.Th>
    </Table.Tr>
</Table.Thead>
```

_Tbody_ is the container for rows.

```tsx
<Table.Tbody>{rows}</Table.Tbody>
```

# Table from data prop



We provide the complete data as a single object for a single prop:

-   The `caption` property defines the table's title
-   The `head` property is the array of headers.
-   The `body` array is the list of items. Each item is an array with bare values

```tsx
const tableData: TableData = {
    caption: "Some elements from periodic table",
    head: ["Element position", "Atomic mass", "Symbol", "Element name"], // headers
    body: [
        // items
        [6, 12.011, "C", "Carbon"],
        [7, 14.007, "N", "Nitrogen"],
        [39, 88.906, "Y", "Yttrium"],
        [56, 137.33, "Ba", "Barium"],
        [58, 140.12, "Ce", "Cerium"],
    ],
}
```

### data prop

We provide such object to the `data` prop. Mantine then creates the markup automatically.

```tsx
<Table data={tableData} />
```

# TextInput



TextInput is an abstraction over `<input type=text>`. It inherits most props from `<Input>`. We describe all props here.

### props

-   Set the main label with `label`. A label describes the input's purpose.
-   Add an optional secondary label with `description`
-   Add some placeholder text with `placeholder`.
-   Add icons, visually inside the input, with `leftSection` and `rightSection`.
-   Mark the input as `required`. Mantine automatically adds an asterisk, unless we remove it with `withAsterisk`.

# NumberInput



_NumberInput_ is a `<input type=text>` under the hood. This enables more freedom into what is displayed in the input. For example, we can display formatting commas.

The value we get is not consistently a number. For example, we get an empty string when the input is empty.

### options

-   Forbid decimal numbers with `allowDecimal`. They are allowed by default.
-   Forbid negative numbers with `allowNegative`. They are allowed by default.
-   Clamp the value between `min` and `max`. Determine how the value should clamp with `clampBehavior`:
    -   Forbid values outside the limits at all times with `strict`.
    -   Clamp after input on `blur`. This is the default.
    -   Never clamp (`none`)

As a text input, it supports a _label_, a _description_ (secondary label) and a _placeholder_.

### state

Work with the _string_ and _number_ type union:

```tsx
const [value, setValue] = useState<string | number>("")
return <NumberInput value={value} onChange={setValue} />
```

Work with a _number_ only. In this case, we only update state if the value is a number. When the NumberInput is empty, the state may have a ghost value. We clear the ghost value on blur if the field is empty.

```tsx
const [value, setValue] = useState<number>(0)

return (
    <NumberInput
        value={value}
        onChange={(value) => {
            if (typeof value === "number") setValue(value)
        }}
        onFocus={(input) => {
            /* clear field to prepare for input if value was 0 */
            if (input.target.value === "0") {
                input.target.value = ""
            }
        }}
        onBlur={(input) => {
            /* reset field to 0 if empty on leaving the field */
            if (input.target.value === "") {
                onChange(0)
            }
        }}
    />
)
```

# FileInput



FileInput is a control that triggers the OS' file selection dialog. It shows information about the current selection. We can customize the flow:

-   Allow selecting multiple files at once with `multiple`. It defaults to false.
-   Restrict selection to a given file type in `accept`, such as `"image/png"`
-   Add a clear button on the right with `clearable`
-   Work with the selected file by providing a handler to `onChange`. The handler receives a _File_ object (or a _File_ array). The handler is called when users close the platform's native File picker or clear the selection.

Other techniques

-   Limit the input's width to truncate long file names with the regular _maw_ prop
-   Add a file icon to the _leftSection_.
-   Opt for the unstyled variant which looks similar to a transparent variant: there is no border or background fill.
-   Shrink the control with _size_.

FileInput inherits props from _Input_

```tsx
<FileInput
    size="xs"
    maw={150}
    onChange={onChange}
    placeholder="Reference Image"
    leftSection={<IconPhoto size={18} stroke={1.5} />}
    clearable
    variant="unstyled"
/>
```

# Native Select



An abstraction over a <_select_> that embeds some <_option_> elements.

We collect options in an array, and assign them to the _data_ attribute. We describe each option with a _label_ and a _value_.

```ts
const options = [
    { label: "Death Knight", value: "deathKnight" },
    { label: "Demon Hunter", value: "demonHunter" },
]
<NativeSelect data={options} />
```

If the _value_ works as a _label_, such as when we want to surface the _value_ in the UI, we can replace the objects with a single string instead. The string acts both as the value and as the label.

```ts
const options = ["deathKnight", "demonHunter"]
```

# SegmentedControl



_SegmentedControl_ allows picking a value among a set of options. The options always stay on screen (Radio button). In that it is different from a Select.

The selected option has a highlight overlay ontop. As the selection changes, Mantine moves the overlay with a smooth animation.

Each option comes with a `label`, which is the user-facing description, and a `value`, which is its unique identifier and which we store in state. We make `value` conform to a type union.

We store the options in `data`. We set the initial selection in `value`.

`onChange` is called on user selection and before browser paint. React prevents any change unless we mutate the state accordingly.

```tsx
type AIProvider = "GPT" | "IMAGEN"

const [provider, setProvider] = useState<AIProvider>("GPT")

<SegmentedControl
    radius="md"
    size="sm"
    value={provider}
    bg={"transparent"}
    onChange={(v) => setProvider(v as AIProvider)}
    data={[
        { label: openAILabel, value: "GPT" },
        { label: geminiLabel, value: "IMAGEN" },
    ]}
/>
```

# Button



An abstraction over a \<button\>.

### button specifics

-   Pick the overall appearance with `variant`:

    -   _filled_ uses bright colors. (default)
    -   _light_ uses toned down colors.
    -   _outline_
    -   _subtle_
    -   _gradient_
    -   _default_

-   Pick the `color` tint. It defaults to the theme's _primaryColor_, aka Mantine's blue.
-   Opt for a fluid button (fill the container) with `fullWidth`.
-   Opt for compact version with `size`, and control the font size.
-   Show the loading spinner appearance (and disable the button) with `loading`. We customize the loader with `loaderProps`.
    (see Loader component)
-   `disabled`, sets the appearance and behavior to disabled. the disabled
    appearance is the same across all variants.
-   `gradient`, sets the gradient's colors and direction. It requires using
    the _gradient_ variant.

### other options

-   `leftSection`, `rightSection`, for example for an icon.

```tsx
<Button rightSection={<IconDownload size={14} />}>Download</Button>
```

### Button not submitting form by default

Mantine adds _type=button_ on the underlying \<button\>. It prevents the
button from triggering the form submit, when pressed inside a \<form\>. We set _type=submit_ if needed.

### providing an onClick handler

The handler specifies which action to perform on click. This action
usually does not depend on any information related to the click event.

Still, the handler receives the event as an argument. If we define the
handler somewhere else than inline, we must indicate its typing. The
argument it takes is of type Event.

More specifically, the event is of type
`React.MouseEvent<HTMLButtonElement >`.

The `HTMLButtonElement` type parameter indicates the type of the
_target_ of the event, which in this case is a \<button\> element.

The handler is not supposed to return anything.

Handler type signature

```tsx
onClick: React.MouseEvent<HTMLButtonElement> => void
```

shortcut type

```tsx
onClick: React.MouseEventHandler<HTMLButtonElement>
```

# Button.Group



We create a button cluster that glues up the buttons horizontally (default), or vertically.

```tsx
<Button.Group>
    <Button variant="default">First</Button>
    <Button variant="default">Second</Button>
    <Button variant="default">Third</Button>
</Button.Group>
```

# ActionIcon



### icon button

ActionIcon serves the "icon as a button" pattern. UI-wise, the idea is
that the icon is expressive enough to be self-explanatory, with no need
for accompanying text, for example the "trash" icon refers to the
"delete" action.

Technically it is a container that is distinct from the icon, that must
be added as a child.

It gives its child icon the behaviour of a button, and it customizes its
appearance according to the selected variant.

-   `variant`: same variants as Button's variants. To get a naked icon effect,
    we select _subtle_ or _transparent_.
-   `size`: the container's size impacts the hover and active zone, and the
    icon scale.

### required child icon

As a wrapper, it impacts the concrete child icon.

We may still set _size_ directly on the child Icon.

```tsx
<ActionIcon variant='default'>
	<IconMail size={14} stroke={..?}/>
</ActionIcon>
```

# Pagination



we provide:

-   the `total` number of pages
-   the `value` of the cursor aka selected page number.
-   the `onChange` handler
-   (optional) `withControls`, to show previous and next arrows, defaults to
    true.
-   (optional) `withEdges`, to show first and last arrows, default to false.
-   (optional) `size`, to get bigger or smaller pagination control, defaults
    to _md_
-   (optional) `radius`, to get rounder or squarer controls, defaults to
    _md_

```tsx
const [activePage, setActivePage] = useState<number>(1)
```

```tsx
<Pagination total={10} value={activePage} onChange={setActivePage} />
```

# Modal



Overlay some UI on top of the application. Dim the rest of the app while opened.

```tsx
<Modal opened={opened} onClose={close}>
{/* Modal content */}
</Modal>
```

Modal works with a boolean state variable to control the display (plugged on the `opened` prop).

Modal also works with an `onClose` handler, called on dismissal attempts, and responsible for toggling back the state to closed, or for denying the dismissal.

reminder: Mantine's _useDisclosure_ provides a boolean state variable, and `open` and `close` state-mutation functions, which are fitting for a modal:

```ts
const [opened, { open, close }] = useDisclosure(false);
```

The following actions qualify as attempts to dismiss:

- press the escape key
- click outside
- click the close button (if displayed)

We usually open the modal with a button:

```tsx
<Button onClick={open}>
        Open modal
</Button>
```

The inner content is commonly form elements: some inputs and a submit button.

### defaults

- the modal has a top section with a close button
- `radius` adheres to *theme.defaultRadius* which defaults to 4px.

### overrides

-   remove the close button with `withCloseButton`, which can remove the header altogether.
-   center the modal with `centered`.
-   add a `title`, which can be any React node (not text-only).
-   control the dimming with `overlayProps`. The dimming is done by an underlying `<Overlay>`.
-   [more overrides](https://mantine.dev/core/modal/?t=props)

# Menu



A menu that gathers a set of controls, that we display conditionally. `Menu` manages the opened state automatically.

The user toggles the menu by clicking the control that lives in `Menu.Target`.

We add a set of `Menu.Item` which are `<button>` under the hood.

We may separate two different sections with `Menu.Divider`. We may give a section a label with `Menu.Label`.

### overall structure

```tsx
<Menu shadow="md">
    <Menu.Target>
        <Button>Toggle menu</Button>
    </Menu.Target>
    <Menu.Dropdown>/* */</Menu.Dropdown>
</Menu>
```

### menu proper

```tsx
<Menu.Dropdown>
    <Menu.Label>Application</Menu.Label>
    <Menu.Item leftSection={<IconSettings size={14} />}>Settings</Menu.Item>
    <Menu.Item leftSection={<IconMessageCircle size={14} />}>Messages</Menu.Item>
    <Menu.Divider />
    <Menu.Label>Danger zone</Menu.Label>
    <Menu.Item leftSection={<IconArrowsLeftRight size={14} />}>Transfer</Menu.Item>
    <Menu.Item leftSection={<IconTrash size={14} />}>Delete</Menu.Item>
</Menu.Dropdown>
```

# Title

Thin abstraction over a heading element. It uses a HTML heading under the hood, _h1_ by default.

It removes the user agent stylesheet's default margin by setting them to 0. It keeps the bold font weight.

The font size, font weight, and line height, come from _theme.headings_.

The default theme defines five font sizes:

-   h5 comes at 16px
-   h4 comes at 18px
-   h3 comes at 22px
-   h2 comes at 26px
-   h1 comes at 34px

We set the heading as follows:

-   `order`: pick the underlying html element, such as _1_ for _h1_. It defaults to h1. Affects the font-size by default.
-   `size`: override the font-size caused by _order_. we pick a size as a number or as a heading in the
    heading hierarchy such as _h5_.
-   `lineClamp`: set the maximum number _n_ of lines. If not set, the browser allow multiple lines for a heading element. If truncation happens, it shows an ellipsis thanks to _text-overflow: ellipsis_.

```tsx
<Title order={3} size={"h5"}>
    Daybreak
</Title>
```



# Text

A container for some text content.

It is a `<p>` element under the hood by default, but we may set it to be another element such as an anchor tag or a span with the `component` prop.

It removes default margins by setting the (vertical) margin to 0.

It comes with some style affecting the font size, the font family and the line height, which is 1.55 by default. We may set it to inherit all those styles instead by adding the `inherit` prop.

```tsx
<Text c="dimmed">Dimmed text</Text>
```



# Box

A neutral wrapper, similar in essence to _div_ or _span_, which may affect its children through Mantine style props:

```tsx
<Box fz={12}>/* */</Box>
```



# Bar Chart



packages

```pug
@mantine/charts
recharts
```

stylesheet

```tsx
import "@mantine/charts/styles.css"
```

### bar-chart logic

for each index, display one or several bars. We assume one bar for each
index.

### data for a given index

The chart library expects an object for each index. The object contains
raw data. Among this data, we select which property acts as the label.
The remaining properties may act as magnitude.

```tsx
{month: "Jan", workouts: 17},
{month: "Feb", workouts: 18}
```

### indicate data's shape

We indicate:

-   the property that acts as the label, here month
-   for each property that we want to act as a magnitude, we indicate: the
    property's name (here workouts) the color for that bar, and the
    label for that bar.

In the following example, _workouts_ provides the magnitude for the
unique serie.

```tsx
<BarChart
    data={}
    h={300}
    dataKey="month" // key that provides label
    series={[
        // bar(s) configuration
        { name: "workouts", color: "blue.6", label: "Workouts" },
    ]}
/>
```

Each magnitude's property, as it spreads over all the indexes, makes a
distinct serie. For example, the ipadSales, the iponeSales, and the
macSales make each one a distinct serie.

# Progress

Progress is a replacement for the native `<progress>` element. It displays a linear bar. It uses a regular _div_ under the hood.

We may opt for a striped bar, or even an animated striped bar.

### simple progress bar

-   `value`: from 0 to 100
-   `size`: the vertical size, aka how thick it is. Defaults to `8px` through default _md_.
-   `radius`: defaults to `4px` through default _sm_. The default size and radius lead to a perfect semi circle border.
-   `color`: defaults to `blue`
-   `animated`: enable a striped pattern and animate the stripes.
-   `striped`: enable a striped pattern.
-   `transitionDuration`: set the duration of the animation that occurs when the value changes, in ms. Defaults to 100.

```tsx
<Progress value={50} />
```

### compound progress bar • segmented bar

We may have several segments.

-   The container is `Progress.Root`
-   Each segment is a `Progress.Section`
-   We may add a segment label with `Progress.Label`

We may make the label have a smart color with `autoContrast`.

```tsx
<Progress.Root>
    <Progress.Section value={20} color="indigo">
        <Progress.Label>Documents</Progress.Label>
    </Progress.Section>
    <Progress.Section value={50} color="orange">
        <Progress.Label>Photos</Progress.Label>
    </Progress.Section>
</Progress.Root>
```



# RingProgress

RingProgress displays a circular, segmented bar.

In the simplest form, we may use it as a circular progress bar, with a single bar showing the progress over the background track.

We may also use it as a segmented, Donut Chart, where one section represents a quantity and has a dedicated bar.

```tsx
<RingProgress
    sections={[{ value: 35, color: progressColor, tooltip: "35%" }]}
    rootColor={trackColor}
    size={30}
    thickness={4}
    roundCaps
/>
```

The Donut chart version has multiple sections:

```tsx
 sections={[
        { value: 40, color: 'cyan' },
        { value: 15, color: 'orange' },
        { value: 15, color: 'grape' },
      ]}
```



# Avatar

The Avatar component may work with the user profile's image or may generate an avatar based on its name's initials. In absence of valid image or name, it falls back to a generic user icon automatically.

The border is round by default, as it sets the _border-radius_ to 1000px.

The avatar size is 36px by default.

Mantine ensures the avatar remains square, cropping the image if needed, and that it covers the whole area, thanks to _object-fit: cover_.

### provide an image

```tsx
<Avatar src={imageURL} alt="John's portrait" />
```

### provide a name

```tsx
<Avatar name={name} />
```

### request a generic icon intentionally

if we omit _src_ and _name_, we always get a generic icon.

```tsx
<Avatar />
```



# Notifications

### setup

```bash
npm install @mantine/notifications
```

```ts
import "@mantine/notifications/styles.css" // here
```

```tsx
<MantineProvider>
    <Notifications />
    {/* Your app here */}
</MantineProvider>
```

```tsx
import { notifications } from "@mantine/notifications"
```

### create notification

we create a notification. We may set:

-   an `id`, if we intend to update this notification later on
-   `loading` to display a spinner
-   `autoClose` to false, to keep the notification on-screen until dismissed. By default, the notification closes automatically. We may set the delay by providing a duration in milliseconds.
-   `position` to set it somewhere else than bottom-right.

`message` is required, while `title` is optional.

```tsx
notifications.show({
    id: task.id,
    color: "white",
    title: "Generating...",
    message: task.prompt,
    autoClose: false,
    loading: true,
    position: "top-right",
    radius: "xl",
    withCloseButton: false,
})
```

### update notification with id

If the update indicates completion, we may show a completion icon, provide a completion text and plan for an auto-close.

```tsx
notifications.update({
    id: task.id,
    color: "gray",
    title: "Image successfully created",
    message: task.prompt,
    icon: <IconCheck size={18} />,
    loading: false,
    autoClose: 2500,
    radius: "xl",
})
```



# useForm

Gather data from user and send it to a server. Send it as-is or after
some (client-side) validation and/or transformation.

In React, a form uses either controlled or uncontrolled inputs. Mantine
provides both options.

Mantine's _useForm_ provides a convenient way to
specify the form's initial data and the validation and/or transformation to
perform on submit.

### Overview

We work with a regular \<form\>, which embeds a set of inputs and a submit button.

We provide initial data in an object (_initialValues_). The user may
edit data through the inputs.

On submit, Mantine collects the data and provide it to the validator
and/or transformer. Then, it provides the processed data to the
callback, in principle for it to send it to the server.

When an initial value has no matching input (invisible, uneditable
property), Mantine still collects it.

### main steps

-   we create a _configuration_ object
-   We compute a configured _form_ object, through
    _useForm_(_configuration_)
-   We generate the form-submit handler with _form.onSubmit(f)_, where f is
    our callback to handle the processed data. The form-submit handler takes
    an event as argument, and is assigned to the \<form\> _onSubmit_
    attribute, which is the react version of standard _onsubmit_.
-   We add attributes to the form inputs so that they interoperate. we
    spread _form.getInputProps(email)_ to add the relevant attributes on the
    input, depending if it is controlled or uncontrolled: _value_ if it is
    controlled, _initialValue_ and _ref_ if it is uncontrolled. They also
    get _onChange_ and _onBlur_.

init form

```tsx
const form = useForm({ // config
  	initialValues: {x: "", y: ""},
	validate: f
	transformValues: (collected) => processed
})
```

form callback

```tsx
function my_callback(data) {
    data.x
    data.y
}

const mantineEventHandler = form.onSubmit(my_callback)
```

wire up

```tsx
form onSubmit={e => mantineEventHandler(e)}
	TextInput label="x" {...form.getInputProps('x')}
	TextInput label="x" {...form.getInputProps('y')}
	TextInput label="x" {...form.getInputProps('z')} // z is not part of initial values, but may still be included if input is changed}
/form
```

### initial value or not.

Mantine collect properties from the initial values, even if there is no
matching input, and even if the value is null or undefined, and provide
them for processing.

If an input is connected to an initial value that does not exist, it is
effectively initialized to undefined, which will generate a React
warning. Mantine will collect the value of that input and associate with
the key provided in form.getInputProps??

### initial value for a TextInput

The initial value for a TextInput should no be null: it triggers a React
warning. It should also not be set to undefined. Instead, we should
initialize to empty string. We may do post-processing in the transformer
to change the empty string to null.

### utils

```tsx
// get current form values
form.values

// Set all or some form values
form.setValues(values)

// Set all form values using the previous state
form.setValues((prev) => ({ ...prev, ...values }))

// Set value of single field
form.setFieldValue("path", value)

// Set value of nested field
form.setFieldValue("user.firstName", "Jane")

// Resets form.values to initialValues,
// clears all validation errors,
// resets touched and dirty state
form.reset()

// Sets initial values, used when form is reset
form.setInitialValues({ values: "object" })
```



# useLocalStorage



`useLocalStorage` exposes an API similar to `useState`, but uses the local storage as a single source of truth. It requires a `key` that describes the local storage entry, and a `defaultValue` for when such entry is missing.

```tsx
const config = {
    key: "default-ai-provider",
    defaultValue: "GPT",
}
```

### synchronous version (opt-in)

When the component mounts, the hook attempts to read a persisted value from the local storage, and initializes the state with it. If the entry is missing, it creates one with `defaultValue`, and initialize the state with it.

```tsx
const config = {
    // ..
    // opt-in for the synchronous version
    getInitialValueInEffect: false,
}
```

### asynchronous version (default)

In the asynchronous version, the hook immediately initializes the state with the default value, to avoid delaying the first paint. The local storage lookup is implemented as an effect that runs later on, after the first paint. Only then it may push the persisted value to the state.

Having the first paint ignoring the persisted value is not always desirable, that's why we may opt-in for the synchronous version.

### exposed API

The hook exposes the state value and the dispatch method. It also exposes a method to remove the entry:

```tsx
const [provider, setProvider, removeEntry] = useLocalStorage<AIProvider>(config)
```

The hook listens for changes in state and updates the local storage accordingly.

# useDisclosure



A wrapper around `useState<boolean>`. It exposes a boolean state variable and provides helper methods which use terminology related to UI elements being opened or closed, such as `open()` and `close()`, in place of `setIsOpened(true/false)`.

```tsx
const [opened, { open, close, toggle }] = useDisclosure(false)
```

# useMantineColorTheme



We want to read the current `colorScheme`, or set it to a value: _dark_ or _light_.

Mantine saves the selected `colorScheme` in localStorage.

Before the App appears on-screen, Mantine checks the localStorage for any saved `colorScheme`, so that the first paint is done with the correct `colorScheme`.

```tsx
const { colorScheme, setColorScheme } = useMantineColorScheme()
// also: toggleColorScheme and clearColorScheme
```

Mantine

Syntax

GitHub Flavored Markdown (GFM)

# Syntax

-   [markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
-   [github guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)

### headings

    # H1
    ## H2
    ### H3

### horizontal line

    ---

### inline code

    The call to `fetch()` was breaking the app.

The call to `fetch()` was breaking the app.

### block of code

    ```typescript
    <Box>Hello World!</Box>
    ```

```typescript
<Box>Hello World!</Box>
```

| language specifier |
| ------------------ |
| typescript         |
| javascript         |
| tsx                |
| jsx                |
| bash               |



# GitHub Flavored Markdown (GFM)

it adds features such as code blocks with three backticks. It's the
prevalent syntax, and is adopted by github and discord.
