AccueilGuidesInstallation

Installation

1. Prérequis
Alveole s’installe dans une application Expo (Expo Router) qui utilise Tamagui 1.x. Les composants sont rendus sur iOS, Android et web.Les dépendances natives requises par @alveole/components (expo-router, expo-web-browser, react-native-svg, react-native-safe-area-context, tamagui et les paquets @tamagui/*…) sont déclarées en peerDependencies : les installer avec `npx expo install` pour obtenir les versions compatibles avec le SDK Expo.
2. Installer les paquets
Tous les paquets @alveole/* doivent avoir exactement le même numéro de version, sans ^ ni ~. Ils sont publiés ensemble et s’appuient les uns sur les autres : mélanger les versions provoque des erreurs de types ou de rendu difficiles à diagnostiquer.Pour monter de version, changer tous les paquets @alveole/* en même temps, y compris la clé allowScripts.Le script postinstall de @alveole/components copie pdf.min.mjs et pdf.worker.min.mjs dans public/ : le visualiseur PDF en a besoin sur le web. npm ne l’exécute que s’il est autorisé dans allowScripts, avec le même numéro de version que les paquets.Ces deux fichiers sont régénérés à chaque installation : les ajouter au .gitignore du projet.
npm install --save-exact @alveole/components@1.10.0 @alveole/core@1.10.0 @alveole/storybook@1.10.0 @alveole/theme@1.10.0
npm install --save-dev --save-exact @alveole/eslint-config@1.10.0
package.json
{
"dependencies": {
"@alveole/components": "1.10.0",
"@alveole/core": "1.10.0",
"@alveole/storybook": "1.10.0",
"@alveole/theme": "1.10.0"
},
"devDependencies": {
"@alveole/eslint-config": "1.10.0"
},
"allowScripts": {
"@alveole/components@1.10.0": true
}
}
.gitignore
# Copiés par le postinstall de @alveole/components
public/pdf.min.mjs
public/pdf.worker.min.mjs
3. Configurer ESLint
L’application doit utiliser la configuration ESLint d’Alveole. Elle connaît les conventions des composants et évite les erreurs de lint qu’une configuration maison signalerait à tort. ESLint 9 ou 10 sont acceptés.eslint.config.js
const { defineConfig } = require('eslint/config');
const alveoleConfig = require('@alveole/eslint-config');
module.exports = defineConfig([
...alveoleConfig,
{
settings: {
react: {
version: '19.2',
},
},
},
]);
4. Configurer Tamagui
Les composants Alveole reposent sur Tamagui 1.x. L’application déclare sa configuration Tamagui, la référence dans package.json et active le plugin Babel, qui extrait le CSS en production.tamagui.config.ts
import { defaultConfig } from '@tamagui/config/v4';
import { createTamagui } from 'tamagui';
const config = createTamagui(defaultConfig);
export type Conf = typeof config;
declare module 'tamagui' {
interface TamaguiCustomConfig extends Conf {}
}
export default config;
babel.config.js
module.exports = function (api) {
api.cache(() => process.env.NODE_ENV);
const isDev = process.env.NODE_ENV !== 'production';
return {
presets: ['babel-preset-expo'],
plugins: [
[
'@tamagui/babel-plugin',
{
components: ['tamagui'],
config: './tamagui.config.ts',
disableDebugAttr: isDev,
disableServerOptimization: isDev,
...(isDev ? {} : { cssPath: './.tamagui/app.css', emitSingleCSSFile: true }),
},
],
],
};
};
package.json
{
"tamagui": {
"config": "./tamagui.config.ts"
}
}
5. Brancher l’AlveoleProvider
AlveoleProvider (@alveole/components) monte, dans l’ordre attendu par les composants, la pile obligatoire : zones sûres, thème Alveole (polices, couleurs, typographies), Tamagui, clavier et notifications. Il se place à la racine, dans app/_layout.tsx, et reçoit la config Tamagui de l’application.Par défaut, AlveoleProvider affiche un indicateur de chargement le temps de charger les polices. Une application qui a son propre splash screen passe loader={false} et masque son splash dans onReady.Les providers propres à l’application (PageMetaProvider pour les balises <meta> sur le web, AppUpdateProvider, LinkAccessContext) se placent sous AlveoleProvider. Une application qui monte déjà son propre KeyboardProvider passe keyboardProvider={false}.app/_layout.tsx
import { AlveoleProvider, PageMetaProvider } from '@alveole/components';
import { Slot } from 'expo-router';
import tamaguiConfig from '../tamagui.config';
import config from '../alveole.config';
export default function RootLayout() {
return (
<AlveoleProvider tamaguiConfig={tamaguiConfig} palette={config.palette}>
<PageMetaProvider meta={[]}>
<Slot />
</PageMetaProvider>
</AlveoleProvider>
);
}
6. Personnaliser les couleurs
Les couleurs se surchargent dans un fichier alveole.config.ts à la racine du projet, importé par le layout et passé à AlveoleProvider via la prop palette.La palette est partielle : seules les clés fournies remplacent celles d’Alveole. Les valeurs viennent de préférence des nuanciers exportés par @alveole/theme (Colors.RougeGroseille, Colors.BleuCaptive…) ; la rubrique Thème › Couleurs liste les clés disponibles.La clé light cible les jetons sémantiques du thème clair (artwork, background, border, text) ; les clés de premier niveau (primary, background.button, stepper…) ciblent les couleurs propres aux composants.alveole.config.ts
import { Colors, type DeepPartial, type Palette } from '@alveole/theme';
const palette: DeepPartial<Palette> = {
light: {
background: {
'action-high-primary': Colors.RougeGroseille['main-465'],
'action-high-primary-hover': Colors.RougeGroseille['200'],
'alt-primary': Colors.RougeGroseille['975'],
},
border: {
'action-high-primary': Colors.RougeGroseille['main-465'],
},
text: {
'title-primary': Colors.RougeGroseille['main-465'],
'active-primary': Colors.RougeGroseille['main-465'],
},
},
primary: Colors.RougeGroseille['main-465'],
background: {
button: {
primary: {
default: Colors.RougeGroseille['main-465'],
hover: Colors.RougeGroseille['200'],
},
},
},
stepper: {
current: Colors.RougeGroseille['625'],
success: Colors.RougeGroseille['main-465'],
},
};
export default { palette };
7. Thème dynamique (facultatif)
Quand les couleurs dépendent de données chargées à l’exécution (une société, un client), fusionner alveole.config avec la palette calculée grâce à deepMerge (@alveole/theme), puis passer le résultat au ThemeProvider. deepMerge ignore les valeurs absentes : une palette partielle ne remplace que ses clés.providers/ClientThemeProvider.tsx
import { deepMerge, ThemeProvider, type DeepPartial, type Palette } from '@alveole/theme';
import React from 'react';
import config from '../alveole.config';
export const ClientThemeProvider = ({
clientPalette,
children,
}: {
clientPalette?: DeepPartial<Palette>;
children: React.ReactNode;
}) => {
const color = React.useMemo(() => deepMerge(config.palette, clientPalette), [clientPalette]);
return <ThemeProvider color={color}>{children}</ThemeProvider>;
};
8. Configurer Jest
@alveole/components et Tamagui sont publiés en ESM et importent des fichiers .css : Jest doit les transformer au lieu de les ignorer, et remplacer les .css par un stub.Certains modules natifs chargés par les composants (expo-asset pour le favicon de PageHead, matchMedia pour Reanimated) n’existent pas dans l’environnement de test : les simuler dans jest.setup.js.jest.config.js
const webPreset = require('jest-expo/web/jest-preset');
const [babelModule, babelOptions] = webPreset.transform['\\.[jt]sx?$'];
module.exports = {
...webPreset,
setupFiles: [...(webPreset.setupFiles ?? []), '<rootDir>/jest.setup.js'],
moduleNameMapper: {
...webPreset.moduleNameMapper,
'\\.css$': '<rootDir>/jest.cssStub.js',
},
transform: {
...webPreset.transform,
'\\.[jt]sx?$|\\.mjs$': [babelModule, babelOptions],
},
// On transforme tout node_modules, sauf les plugins Babel eux-mêmes.
transformIgnorePatterns: ['/node_modules/react-native-reanimated/plugin/', '/node_modules/@react-native/babel-preset/'],
};
jest.cssStub.js
module.exports = {};
jest.setup.js
jest.mock('expo-asset', () => ({
Asset: { fromModule: () => ({ uri: 'test-file-stub' }) },
}));
if (typeof window !== 'undefined' && !window.matchMedia) {
window.matchMedia = () => ({
matches: false,
media: '',
onchange: null,
addListener: () => {},
removeListener: () => {},
addEventListener: () => {},
removeEventListener: () => {},
dispatchEvent: () => false,
});
}
9. Monter le catalogue dans l’application (facultatif)
@alveole/storybook sert à afficher, dans l’application elle-même, le catalogue des composants Alveole et ceux du projet. Deux routes suffisent : la liste et la fiche d’un composant. Les écrans Couleurs, Typographies et Constantes s’ajoutent de la même façon.Le catalogue n’a d’intérêt qu’en développement : y donner accès par un bouton affiché sous __DEV__.app/ui-kit/index.tsx
import * as AlveoleStories from '@alveole/components/stories';
import { StoriesScreen, toStoryModules } from '@alveole/storybook';
const stories = toStoryModules(AlveoleStories);
export default function UIKitIndexScreen() {
return (
<StoriesScreen
stories={stories}
title="UI Kit - Composants"
getStoryHref={story => `/ui-kit/components/${encodeURIComponent(story.default.title)}`}
/>
);
}
app/ui-kit/components/[component].tsx
import * as AlveoleStories from '@alveole/components/stories';
import { StoryDetailScreen, findStoryByTitle, toStoryModules } from '@alveole/storybook';
import { useLocalSearchParams } from 'expo-router';
const stories = toStoryModules(AlveoleStories);
export default function UIKitComponentScreen() {
const { component } = useLocalSearchParams<{ component: string }>();
return <StoryDetailScreen story={findStoryByTitle(stories, component)} notFoundMessage="Composant introuvable" />;
}
10. Vérifier
Afficher un premier composant pour valider l’installation, puis lancer le lint et le typecheck de l’application.app/index.tsx
import { Button } from '@alveole/components';
export default function Home() {
return <Button variant="primary" title="Alveole est installé" onPress={() => {}} />;
}
npx eslint .
npx tsc --noEmit
Alveole UI Kit — v2.0.0-alpha.30