From 73f65ed2e60bd2e321cea7c8d4cc89fa51ba5718 Mon Sep 17 00:00:00 2001
From: Andrew Welch <andrew@nystudio107.com>
Date: Wed, 28 Feb 2024 18:17:37 -0500
Subject: [PATCH] feat: Add documentation for Craft Cloud usage with Vite
 ([#83](https://github.com/nystudio107/craft-vite/pull/83))

---
 docs/docs/index.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/docs/index.md b/docs/docs/index.md
index 19b4938..41be2e9 100755
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -911,6 +911,44 @@ So for example:
     ) }}
 ```
 
+## Craft Cloud
+During a [build](https://craftcms.com/knowledge-base/cloud-builds), Craft Cloud deploys static assets to a CDN, so you’ll need to configure the plugin to use the appropriate URLs:
+```php
+<?php
+// config/vite.php
+
+use craft\cloud\Helper as CloudHelper;
+
+return [
+    'manifestPath' => CloudHelper::artifactUrl('dist/.vite/manifest.json'),
+    'serverPublic' => CloudHelper::artifactUrl('dist/'),
+];
+```
+This helper function returns a CDN URL that includes your project and environment identifiers, like this:
+```
+https://cdn.craft.com/{project-uuid}/builds/{environment-uuid}/artifacts/dist/
+```
+Outside of Cloud, this behaves as though it were prepended with `@web`.
+If you’d prefer to use an on-disk `manifestPath` when working locally (instead of a URL), the `CloudHelper::isCraftCloud()` function lets you switch based on the environment:
+```php
+<?php
+// config/vite.php
+
+use craft\cloud\Helper as CloudHelper;
+
+return [
+    'manifestPath' => CloudHelper::isCraftCloud() ? CloudHelper::artifactUrl('dist/.vite/manifest.json') : '@webroot/dist/.vite/manifest.json',
+    'serverPublic' => CloudHelper::artifactUrl('dist/'),
+];
+```
+Additionally, your Vite config should have [public `base`](https://vitejs.dev/guide/build.html#public-base-path) set to use the same CDN URL. In Craft Cloud’s build pipeline, this is exposed as an [`CRAFT_CLOUD_ARTIFACT_BASE_URL` environment variable](https://craftcms.com/knowledge-base/cloud-builds#build-command):
+```javascript
+// vite.config.js
+export default ({ command }) => ({
+  base: command === 'serve' ? '' : `${process.env.CRAFT_CLOUD_ARTIFACT_BASE_URL || ''}/dist/`,
+})
+```
+
 ## Vite Roadmap
 
 Some things to do, and ideas for potential features: