# Installation

> La commande colis depuis npm, et le reste de colis construit depuis le dépôt.

Canonical: https://colis-docs.vercel.app/docs/installation · Markdown: https://colis-docs.vercel.app/docs/installation.md

La commande `colis` est publiée sur npm sous le nom `@mdemb/colis` (le nom `colis` seul est refusé
par npm, trop proche de `colors`) :

```sh
npm i -g @mdemb/colis
colis envoyer ./maquette.pdf
colis statut <CODE>
```

Sans rien configurer, ces commandes passent par le service public de colis
([colis-tau.vercel.app](https://colis-tau.vercel.app)), ouvert à tous et donc limité : un fichier de 100 Mo au plus, gardé 24 h au plus, et 20 envois par heure depuis une même adresse. Voir [CLI](https://colis-docs.vercel.app/docs/cli#trois-façons-de-travailler).

Le nœud n8n est publié aussi, sous le nom `n8n-nodes-colis` (voir [Webhooks & n8n](https://colis-docs.vercel.app/docs/webhooks#avec-n8n)).
Les paquets `@colis/*` ne sont pas encore publiés : eux, et la page de livraison, se construisent
depuis le dépôt, comme ci-dessous.

## Prérequis

- **Node 20** ou plus récent. Le dépôt fixe Node 22 dans `.node-version`, et la CI teste 20, 22 et 24.
- **[Bun](https://bun.com) 1.2** ou plus récent, qui installe les dépendances et orchestre les tâches
  avec Turborepo. Les outils eux-mêmes (tsup, vitest, next) tournent sur Node.

## Cloner et construire

```sh
git clone https://github.com/mamadouwhile/colis.git && cd colis
bun install && bun run build
```

`bun run build` lance `turbo build` sur tout l’espace de travail : les paquets sous `packages/`, la
page de livraison, le site et cette documentation. Pour ne construire que ce qui sert à livrer :

```sh
bunx turbo run build --filter=@mdemb/colis --filter=colis-drop
```

Turborepo construit d’abord les dépendances de chaque cible (`@colis/protocol`, puis `@colis/core`).

## La commande `colis`

Le build produit `packages/cli/dist/index.js`. Un alias suffit :

```sh
alias colis="node $PWD/packages/cli/dist/index.js"
colis --version
```

Mettez l’alias dans votre `~/.bashrc` ou `~/.zshrc`, avec le chemin absolu du dépôt, pour le garder.
Chaque commande est décrite dans [CLI](https://colis-docs.vercel.app/docs/cli).

## La page de livraison

`templates/drop` se construit depuis le monorepo, parce qu’elle dépend de `@colis/core`,
`@colis/protocol` et `@colis/react` en version `^0.1.0` que Bun relie aux paquets locaux. En local :

```sh
bun run --filter colis-drop dev   # http://localhost:3400
```

Sur Vercel, on importe le dépôt entier avec `templates/drop` comme Root Directory :
[Page de livraison](https://colis-docs.vercel.app/docs/page-de-livraison#sur-vercel).

## Le nœud n8n

```sh
bun run --filter n8n-nodes-colis build   # dist/, et les icônes à côté des nœuds
bun run --filter n8n-nodes-colis test
```

L’installer dans une instance n8n auto-hébergée est décrit dans [Webhooks & n8n](https://colis-docs.vercel.app/docs/webhooks#avec-n8n).

## Utiliser les bibliothèques dans votre code

Tant que rien n’est publié, le plus sûr est de travailler dans l’espace de travail : un dossier sous
`apps/`, `examples/` ou `templates/` qui dépend de `@colis/core@^0.1.0`, comme le fait
`templates/drop`. Bun relie alors la version locale.

| Paquet            | Quand l’utiliser                                                                                           |
| ----------------- | ---------------------------------------------------------------------------------------------------------- |
| `@colis/core`     | Votre serveur parle au bucket. Apporte le SDK AWS (`@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`). |
| `@colis/protocol` | Vous écrivez un client ou vérifiez des webhooks. Aucun client S3, donc utilisable dans un navigateur.      |
| `@colis/react`    | Votre app React envoie ou retrouve des colis. Dépend du protocole, jamais du SDK AWS.                      |
| `colis`           | La commande `colis`. Embarque `@colis/core` et `@colis/protocol` : un seul paquet à installer.             |

Chaque paquet est livré en ESM et en CommonJS, avec ses déclarations TypeScript. `@colis/core` ne
tourne que côté serveur : il n’a pas de build navigateur, et aucun chemin de code qui mettrait des
identifiants sous les yeux d’un utilisateur.

## Les commandes du dépôt

```sh
bun run build        # turbo build sur tout l’espace de travail
bun run test         # les tests de chaque paquet et de la page de livraison
bun run type-check
bun run lint
bun run format
```

Voir [Tests](https://colis-docs.vercel.app/docs/tests) pour ce que couvre la suite.