diff --git a/docs/content/0.index.md b/docs/content/0.index.md index eb0d6ea22..9ec5926ff 100755 --- a/docs/content/0.index.md +++ b/docs/content/0.index.md @@ -11,7 +11,7 @@ cta: - /guide secondary: - Try it out → - - https://nimbus.zone + - https://nimbus.town --- #title diff --git a/docs/content/1.guide/1.index.md b/docs/content/1.guide/1.index.md index ab122c3e7..44f647ea0 100644 --- a/docs/content/1.guide/1.index.md +++ b/docs/content/1.guide/1.index.md @@ -2,102 +2,70 @@ ## What is Nimbus? -Nimbus is an alternative way to access your Mastodon account from your browser. +Nimbus is an alternative way to access your Bluesky account from your browser. -Through the Mastodon API, Nimbus provides similar access to posts and actions on posts you expect to be able to do to Mastodon. -You can compose a post (Toot, if you like), boost others' toots, like, and scroll just as you would through your regular server site. +Through the Bluesky API, Nimbus provides similar access to posts and actions on posts you expect to be able to do to Bluesky. You can compose a post, boost others' posts, like, and scroll just as you would through your regular server site. -Why Nimbus, then? -Nimbus provides some features not available through the standard Mastodon web app interface. +You can use Nimbus right in your browser. On a mobile device, you can install the app to your home screen as a [Progressive Web App (PWA)](../80.pwa.md). -- Notifications for the same post combine when they are sequential. No more seeing your same viral joke multiple times in the Notification feed for each like and boost. Now you can see it just one, with a list of who liked or boosted the post just above the post itself. -- You control whether you see boost, like, and follower accounts - all separately! -- See a preview of the profile when someone follows you. +## What is Bluesky? -You can use Nimbus right in your browser. -On a mobile device, you can install the app to your home screen right from your browser for easy access. -(This is called a Progressive Web App, or [PWA](../80.pwa.md).) - -Want to try it out? -Visit https://elk.zone, type in your Mastodon server address, then log in. -Or, visit one of the other Nimbus installs in the [Nimbus ecosystem](https://github.com/elk-zone/elk#ecosystem). - -## What is Mastodon? - -Mastodon is a decentralized microblogging platform. -Mastodon uses the [ActivityPub protocol](https://www.w3.org/TR/activitypub/) to share posts and actions between users within or across different instance servers. +Bluesky is an open-source microblogging platform built on the [AT protocol](https://atproto.com/). It aims to provide a familiar microblogging experience while also granting users control over their personal data using [Personal Data Servers (PDS)](https://atproto.com/guides/glossary#pds-personal-data-server). You can think of the service as something similar to Twitter, but with some key differences. -- Where Twitter is a single site that everyone who uses it belongs to, Mastodon is a platform used by many different sites. -- Where Twitter is a corporation with profit goals and advertisements, Mastodon is a free and open source software tool maintained by volunteers and paid for by patrons and voluntary contributors to their own instance servers and back to the main software project. -- Where Twitter users can only interact with other Twitter users, Mastodon users can talk to users on many other ActivityPub platforms, including services that provide video (PeerTube), photos ([PixelFed](https://pixelfed.org/)), blogs ([WriteFreely](https://writefreely.org/)), and alternative microblogging platforms ([Pleroma](https://pleroma.social/), [Hometown](https://github.com/hometown-fork/hometown), [GoToSocial](https://gotosocial.org/), and their derivatives). +- Where Twitter is a corporation with profit goals and advertisements, Bluesky is an open-source project built on open protocols and maintained by a Public Benefit Corporation. +- Where Twitter users can only interact with other Twitter users, Bluesky users are able to communicate with other ATProtocol-powered platforms. -For more details about Mastodon, see their [website](https://joinmastodon.org/), [blog](https://blog.joinmastodon.org), [docs](https://docs.joinmastodon.org), and [GitHub Repository](https://github.com/mastodon/mastodon). +For more details about Bluesky, see their [website](https://bluesky.social/about), [blog](https://bsky.social/about/blog), [GitHub organization](https://github.com/bluesky-social), [documentation](https://docs.bsky.app/docs/get-started) and the [ATProtocol documentation](https://atproto.com/). -## What is a Mastodon Client? +## What is a Bluesky Client? -A Mastodon Client is software that serves up the posts and activities from a Mastodon server using the [Mastodon API](https://docs.joinmastodon.org/api/). -When you visit or sign in to a Mastodon server, you use the standard Mastodon client or the alternative Advanced Web Interface (that provides a multi-column format). +A Bluesky Client is software that serves up the posts and activities from Bluesky using the [Bluesky API](https://docs.bsky.app/docs/category/http-reference). When you visit or sign in to Bluesky, you use the standard Bluesky client. -A Mastodon client performs similar functions as the standard web interfaces. -Using a client, you can -- View posts from accounts you follow -- Repost and like posts -- Create new posts from your own account -- See what is trending on your server -- View, add, or participate in polls -- Follow, unfollow, mute, and block accounts +A Bluesky client performs similar functions as the standard web interfaces. Using a client, you can: + +- View posts from accounts you follow. +- Repost and like posts. +- Create new posts from your own account. +- Follow, unfollow, mute, and block accounts. ::alert{type="info"} **Note:** Not all clients provide all features. :: -### Installed Mastodon Clients +### Installed Bluesky Clients -You may be most familiar with Mastodon Clients through your phone or tablet. -The app you download from an app store and install on your device to access your Mastodon account is a Mastodon Client. +You may be most familiar with Bluesky Clients through your phone or tablet. The app you download from an app store and install on your device to access your Bluesky account is a Bluesky Client. ::card{icon="logos:android-icon"} #title Android #description -[Fedilab](https://fedilab.app/), [Tusky](https://tusky.app/), or [Tooot](https://tooot.app/), among others. +[Graysky](https://graysky.app/) and [Openvibe](https://openvibe.social/). :: ::card{icon="logos:apple"} #title Apple #description -[Ivory](https://tapbots.com/ivory/), [Ice Cubes](https://apps.apple.com/us/app/ice-cubes-for-mastodon/id6444915884), [Metatext](https://github.com/metabolist/metatext), or [Toot](https://apps.apple.com/app/toot/id1229021451?ls=1) +[Skeets](https://www.skeetsapp.com/), [Graysky](https://graysky.app/), [Openvibe](https://openvibe.social/), or [Croissant](https://croissantapp.com/). :: ::card{icon="mdi:desktop-classic"} #title Desktop #description -[TheDesk](https://thedesk.top/en/), [Whalebird](https://whalebird.social/en), or [Sengi](https://nicolasconstant.github.io/sengi/) +[Skeets](https://www.skeetsapp.com/), [Sky.app](https://github.com/jcsalterego/Sky.app). :: -All of these apps provide some combination of the features a typical Mastodon user expects for their account. - -### Browser-based Mastodon Clients - -Nimbus is a Mastodon Client, but instead of being an app to install on your phone, tablet, or desktop, it is an alternative web site you visit in a browser. - -In addition to Nimbus, there are other browser-based alternative Mastodon clients. -Some include: - -- [Semaphore](https://semaphore.social/), a continuation of the now-frozen [Pinafore](https://pinafore.social/) -- [Sengi](https://nicolasconstant.github.io/sengi/) (Also available as a desktop client) -- [Cuckoo](https://cuckoo.social) - -## Sponsors +All of these apps provide some combination of the features a typical Bluesky user expects for their account. -We want to thank the generous sponsoring and help of: +### Browser-based Bluesky Clients -[![NuxtLabs](/images/nuxtlabs.svg)](https://nuxtlabs.com/) -[![StackBlitz](/images/stackblitz.svg)](https://stackblitz.com/) +Nimbus is a Bluesky Client, but instead of being an app to install on your phone, tablet, or desktop, it is an alternative web site you visit in a browser. -And all the companies and individuals sponsoring Nimbus Team members. +In addition to Nimbus, there are other browser-based alternative Bluesky clients. Some include: -[Find out more about sponsoring Nimbus](/guide/sponsoring). +- [deck.blue](https://deck.blue/), a multi-column interface for Bluesky. +- [SkyFeed](https://skyfeed.app/), an alternative Bluesky app with a powerful feed builder. +- [Ouranos](https://useouranos.app/), a Bluesky client with a focus on simplicity. diff --git a/docs/content/1.guide/3.contributing.md b/docs/content/1.guide/3.contributing.md index 26c4e39a3..1528ccfcd 100644 --- a/docs/content/1.guide/3.contributing.md +++ b/docs/content/1.guide/3.contributing.md @@ -4,9 +4,9 @@ We're really excited that you're interested in contributing to Nimbus! Before su ## Online -You can use [StackBlitz Codeflow](https://stackblitz.com/codeflow) to fix bugs or implement features. You'll also see a Codeflow button on PRs to review them without a local setup. Once the elk repo has been cloned in Codeflow, the dev server will start automatically and print the URL to open the App. You should receive a prompt in the bottom-right suggesting to open it in the Editor or in another Tab. To learn more, check out the [Codeflow docs](https://developer.stackblitz.com/codeflow/what-is-codeflow). +You can use [StackBlitz Codeflow](https://stackblitz.com/codeflow) to fix bugs or implement features. You'll also see a Codeflow button on pull requests (PRs) to review them without a local setup. Once the Nimbus repo has been cloned in Codeflow, the dev server will start automatically and print the URL to open the App. You should receive a prompt in the bottom-right suggesting to open it in the Editor or in another Tab. To learn more, check out the [Codeflow docs](https://developer.stackblitz.com/codeflow/what-is-codeflow). -[![Open in Codeflow](https://developer.stackblitz.com/img/open_in_codeflow.svg)](https://pr.new/elk-zone/elk) +[![Open in Codeflow](https://developer.stackblitz.com/img/open_in_codeflow.svg)](https://pr.new/nimbus-town/nimbus) ## Local Setup @@ -17,7 +17,7 @@ pnpm i pnpm run dev ``` -`Warning`: you will need `corepack` enabled, check out the [Nimbus Contributing Guide](https://github.com/elk-zone/elk/blob/main/CONTRIBUTING.md) for a detailed guide on how to set up the project locally. +`Warning`: you will need `corepack` enabled, check out the [Nimbus Contributing Guide](https://github.com/nimbus-town/nimbus/blob/main/CONTRIBUTING.md) for a detailed guide on how to set up the project locally. We recommend installing [ni](https://github.com/antfu/ni#ni), that will use the right package manager in each of your projects. If `ni` is installed, you can instead run: @@ -48,6 +48,6 @@ nr test - [Vue Macros](https://vue-macros.sxzz.moe/) - More macros and syntax sugar for Vue - [UnoCSS](https://uno.antfu.me/) - The instant on-demand atomic CSS engine - [Iconify](https://github.com/iconify/icon-sets#iconify-icon-sets-in-json-format) - Iconify icon sets in JSON format -- [Masto.js](https://neet.github.io/masto.js) - Mastodon API client in TypeScript +- [ATP API](https://github.com/bluesky-social/atproto/tree/main/packages/api) - ATProtocol API client in TypeScript - [shiki](https://shiki.style/) - A beautiful yet powerful syntax highlighter - [vite-plugin-pwa](https://github.com/vite-pwa/vite-plugin-pwa) - Prompt for update, Web Push Notifications and Web Share Target API diff --git a/docs/content/2.deployment/1.netlify.md b/docs/content/2.deployment/1.netlify.md index 322dd4307..90a50c350 100644 --- a/docs/content/2.deployment/1.netlify.md +++ b/docs/content/2.deployment/1.netlify.md @@ -1,6 +1,6 @@ # Netlify and Cloudflare -Want to host Nimbus for your Mastodon instance? You came to the right place! +Want to host Nimbus by yourself? You came to the right place! For this guide we're going to use Netlify for hosting the app, and Cloudflare for key value storage. Both of which can be used on their free tiers if your instance is small. @@ -8,7 +8,8 @@ For this guide we're going to use Netlify for hosting the app, and Cloudflare fo In order to use Netlify with Nimbus, we'll need to fork the Nimbus repo. -Fork the repository from [https://github.com/elk-zone/elk](https://github.com/elk-zone/elk). Make sure you deselect "Copy the main branch only" if you want to use the stable `release` branch. +Fork the repository from [https://github.com/nimbus-town/nimbus](https://github.com/nimbus-town/nimbus). Make sure you deselect "Copy the main branch only" if you want to use the stable `release` branch. + ![The settings to use for forking the Nimbus repository](/images/selfhosting-guide/github-fork.png) ## Importing the Nimbus repo into Netlify @@ -51,11 +52,13 @@ There are 5 environment variables to add. That's it! All that's left to do is... ## Deploy Nimbus! + On your project page open the Deploys tab, click on "Trigger deploy" and "Deploy site". In a few minutes Nimbus should be up and running! ## Use a custom domain + If you want to use a custom domain, go to "Domain settings" on your Netlify project page, and press "Add custom domain". If your domain is not bought from Netlify, it will ask you to add a CNAME record. Do that. Once the custom domain is added, you'll need to add an SSL/TLS certificate. At the bottom of the page press "Verify DNS configuration" and if it succeeds, press "Provision certificate". If that fails, you may need to wait some time until your DNS propagates. -And that's it! Enjoy your instance's Nimbus! +And that's it! Enjoy Nimbus! diff --git a/docs/content/80.pwa.md b/docs/content/80.pwa.md index 219007a1e..33d7b1600 100644 --- a/docs/content/80.pwa.md +++ b/docs/content/80.pwa.md @@ -1,65 +1,71 @@ # PWA -Nimbus provides a PWA (Progressive Web App) that can be installed on your desktop/device. This allows you to use Nimbus as a native app on your device, and it will work offline. +Nimbus provides a Progressive Web App (PWA) that can be installed on your desktop/device. This allows you to use Nimbus as a native app on your device, and it will work offline. The main goal of the PWA is to provide a native app experience on mobile devices with Web Push Notifications and Web Share Target API capabilities. -Web Share Target will allow you to share content from other apps to Nimbus in mobile browsers. +Web Share Target allows you to share content from other apps to Nimbus in mobile browsers. ## Mobile Support -Some mobile browsers will allow you to install the PWA as a native app, and some others will only allow you to add the PWA to your home screen. +Some mobile browsers allow you to install the PWA as a native app. Others only allow you to add the PWA to your home screen. -If you're using a mobile browser that supports the PWA installation, you will see a banner at the bottom of the screen with the option to install the PWA. +If you're using a mobile browser that supports PWA installation, you will see a banner at the bottom of the screen with the option to install the PWA. -If the browser also supports [beforeinstallprompt](https://web.dev/customize-install/) event, ElK will show a prompt (on the right aside on wide screens, or at top on small screens) to allow you to install the PWA directly. +If the browser also supports the [`beforeinstallprompt`](https://web.dev/customize-install/) event, Nimbus displays a prompt (on the right side on wide screens, or at top on small screens) to allow you to install the PWA directly. -If the browser doesn't support the PWA installation, check following entries: +If the browser doesn't support PWA installation, check the following sections. ### Safari iOS -Right now, you cannot use Web Push Notifications on Safari mobile browsers, since it doesn't support the Web Push API yet at operating system level. +Right now, you can't use Web Push Notifications on Safari mobile browsers, since it doesn't support the Web Push API yet at operating system level. -You can check the status of the Push API on Safari mobile browsers on [this page](https://caniuse.com/notifications). +::alert{type="success"} +See [caniuse](https://caniuse.com/notifications) to see the status of the Push API in Safari for mobile and [firt.dev](https://firt.dev/notes/pwa-ios) to see the status of PWA capabilities in Safari for mobile. +:: -Visit also [this site](https://firt.dev/notes/pwa-ios/) to check the status of PWA Capabilities on Safari mobile browsers. +To install a PWA on Safari, follow these steps: -To install a Progressive Web App (PWA) on Safari, follow these steps: -- Tap the "Share" icon at the bottom of the screen. -- Scroll down and tap "Add to Home Screen". -- Customize the name of the app (if desired) and tap "Add". -- The PWA should now appear on your home screen. +1. Tap the "Share" icon at the bottom of the screen. +2. Scroll down and tap "Add to Home Screen". +3. Customize the name of the app (if desired) and tap "Add". +4. The PWA should now appear on your home screen. ### Other browsers on iOS -Browsers on iOS other than Safari (like Chrome) are very limited on PWA functionalities. Besides Web Push Notifications (like in Safari) not even PWA installation is supported. +Browsers on iOS other than Safari (like Chrome) have limited PWA functionality. In addition to lacking Web Push Notifications (like Safari), PWA installation isn't supported. -If you are using one of these browsers and want to add Nimbus to your homescreen, you will have to use Safari and follow the instructions above. +If you use one of these browsers and want to add Nimbus to your home screen, you need to use Safari and [follow the instructions above](#safari-ios). ### Firefox -To install a Progressive Web App (PWA) on Firefox, follow these steps: -- Look for the install button or icon, usually located in the address bar or in a prompt that appears on the screen. -- Click on the install button or icon and follow the prompts to complete the installation. -- If you don't see an install button or icon, you can look for the PWA in the Firefox menu. Click on the three horizontal lines in the top/bottom right corner of the browser window to open the menu, then click on "Install" option. +To install a PWA on Firefox, follow these steps: + +1. Look for the install button or icon, usually located in the address bar or in a prompt that appears on the screen. +2. Click on the install button or icon and follow the prompts to complete the installation. +3. If you don't see an install button or icon, you can look for the PWA in the Firefox menu. Click on the three horizontal lines in the top/bottom right corner of the browser window to open the menu, then click on "Install" option. ### Chromium based browsers -To install a Progressive Web App (PWA) on Chromium based browsers, such as Google Chrome, Microsoft Edge, or Brave, follow these steps: -- Click on the menu button (three vertical dots) at the top right corner of the screen. -- Select "Install Nimbus as app" or "Install Nimbus to Home screen". -- Customize the name of the app (if desired) and click "Install" or "Add". -- The PWA should now appear on your device's home screen or in your app drawer. +To install a PWA on Chromium based browsers, such as Google Chrome, Microsoft Edge, or Brave, follow these steps: + +1. Click on the menu button (three vertical dots) at the top right corner of the screen. +2. Select "Install Nimbus as app" or "Install Nimbus to Home screen". +3. Customize the name of the app (if desired) and click "Install" or "Add". +4. The PWA should now appear on your device's home screen or in your app drawer. ## FAQ -This FAQ is related to the PWA application on Nimbus, if you can't find the answer to your problem here, you can [file an issue on Nimbus's repository in GitHub](https://github.com/elk-zone/elk). +This FAQ is related to the PWA application for Nimbus. If you can't find the answer to your problem here, [file an issue on Nimbus's repository in GitHub](https://github.com/nimbus-town/nimbus). + + ### Permission denied: enable notifications in your browser -Before enabled push notifications in your browser, you need to enable notifications, Nimbus will instruct the browser to show a notification permission prompt. +Before you enable push notifications in your browser, you need to enable notifications. Nimbus instructs the browser to show a notification permission prompt. -If you cannot see the notification permission prompt, you will need to remove push notification subscriptions, check previous entry. +If you can't see the notification permission prompt, you need to remove push notification subscriptions. Check the previous section for information. ### Your browser supports Web Push Notifications, but does not seem to implement the VAPID protocol. -If you're receiving this error, it means that either your browser doesn't support the VAPID protocol, or something is preventing the VAPID protocol from working in your browser. The VAPID protocol requires the clock to be set correctly on your computer or device, since this is used for certficate checks. Check that your clock is set to the correct date, time and timezone. After setting it correctly, restart your browser and try again. If it is set correctly, and you still receive this message, then your browser doesn't support the VAPID protocol and you will not be able to receive push notifications. +If you receive this error, it means that either: -In Brave Browser, you will need to allow "Use Google Services for Push Messaging" in "Settings" > "Privacy and security". +1. Your browser doesn't support the VAPID protocol. +2. Something is preventing the VAPID protocol from working in your browser. -There is nothing we can do to fix this, you will need to use a browser that supports the VAPID protocol: Chrome, Brave, Edge, Safari, Firefox and Vivaldi. +The following browsers support the VAPID protocol: +- Chrome +- Brave +- Edge +- Safari +- Firefox +- Vivaldi -### Install Nimbus button not working +::alert{type="info"} +In Brave Browser, you need to allow "Use Google Services for Push Messaging" in "Settings" > "Privacy and security". +:: + +The VAPID protocol requires the clock to be set correctly on your computer or device, since this is used for certificate checks. Check that your clock is set to the correct date, time and timezone. After setting it correctly, restart your browser and try again. -There are browsers that allows applications to provide a custom PWA installation prompt, but there are also browsers with that behavior broken, for example Arc browser. +If you still receive this issue after verifying your timezone settings, it means your browser doesn't support the VAPID protocol and you won't be able to receive push notifications. -There is nothing we can do to fix this problem, you will need to check browser documentation to install the PWA. +### Install Nimbus button not working + +Most browsers enable applications to provide a custom PWA installation prompt. Some browsers, such as Arc browser, don't enable this. These issues can't be fixed by Nimbus. Check the browser's documentation for PWA installation instructions. ## PWA Configuration in Nimbus project -By default, Nimbus will enable the PWA integration, but can be disabled by setting `VITE_DEV_PWA` to `false` in your `.env` file. +By default, Nimbus enables PWA integration. You can be disable this by setting `VITE_DEV_PWA` to `false` in your `.env` file. -You can find the configuration options for the PWA in the [config/pwa.ts](https://github.com/elk-zone/elk/blob/main/config/pwa.ts) module. +You can find the configuration options for the PWA in [`config/pwa.ts`](https://github.com/nimbus-town/nimbus/blob/main/config/pwa.ts) module. ### PWA Web Manifest -Right now, there is no support for web manifest internationalization and theme color in any browser, we're using a custom module to generate web manifests for theme color and language variants. +Currently, there is no support for web manifest internationalization or theme color in any browser. We're using a custom module to generate web manifests for theme color and language variants. -Nimbus will generate 2 web manifests per locale, one for light theme and one for dark theme. +Nimbus generates two web manifests per locale: one for light theme and one for dark theme. -You can check web manifest generation on [modules/pwa/i18n.ts](https://github.com/elk-zone/elk/blob/main/modules/pwa/i18n.ts) module. +You can check web manifest generation in [`modules/pwa/i18n.ts`](https://github.com/nimbus-town/nimbus/blob/main/modules/pwa/i18n.ts) module. ### PWA Icons -Nimbus's favicon and PWA icons are generated from [Nimbus's SVG Logo](https://github.com/elk-zone/elk/blob/main/public/logo.svg) via [custom script](https://github.com/elk-zone/elk/blob/main/scripts/generate-pwa-icons.ts), using [sharp](https://github.com/lovell/sharp/) and [sharp-ico](https://github.com/ssnangua/sharp-ico) libraries: -- favicon.ico: transparent 64x64 32-bits icon -- pwa-64x64.png: transparent 64x64 8-bits icon (optimized from 32-bits color) -- pwa-192x192.png: transparent 192x192 8-bits icon (optimized from 32-bits color) -- pwa-512x512.png: transparent 512x512 8-bits icon (optimized from 32-bit color) -- maskable-icon.png: white background 512x512 8-bits icon (optimized from 32-bits color) -- apple-touch-icon.png: white background 180x180 8-bits icon (optimized from 32-bits color) +Nimbus's favicon and PWA icons are generated from [Nimbus's SVG Logo](https://github.com/nimbus-town/nimbus/blob/main/public/logo.svg) via [a custom script](https://github.com/nimbus-town/nimbus/blob/main/scripts/generate-pwa-icons.ts), using the [`sharp`](https://github.com/lovell/sharp/) and [`sharp-ico`](https://github.com/ssnangua/sharp-ico) libraries: -### PWA UI Components +- `favicon.ico`: transparent 64x64 32-bits icon +- `pwa-64x64.png`: transparent 64x64 8-bits icon (optimized from 32-bits color) +- `pwa-192x192.png`: transparent 192x192 8-bits icon (optimized from 32-bits color) +- `pwa-512x512.png`: transparent 512x512 8-bits icon (optimized from 32-bit color) +- `maskable-icon.png`: white background 512x512 8-bits icon (optimized from 32-bits color) +- `apple-touch-icon.png`: white background 180x180 8-bits icon (optimized from 32-bits color) -Nimbus will provide a set of UI components to allow you to customize the PWA installation prompt on browsers with [beforeinstallprompt](https://web.dev/customize-install/) support. +### PWA UI Components -You can find the PWA installation prompt in the [PwaInstallPrompt](https://github.com/elk-zone/elk/blob/main/components/pwa/PwaInstallPrompt.client.vue) component: will be shown on the right aside on wide screens, or at top on small screens. +Nimbus provides a set of UI components that allow you to customize the PWA installation prompt on browsers with [`beforeinstallprompt`](https://web.dev/customize-install/) support. -Nimbus is using prompt for update strategy, so the PWA prompt for update will be shown only if there is a new version of Nimbus available. +You can find the PWA installation prompt in the [`PwaInstallPrompt`](https://github.com/nimbus-town/nimbus/blob/main/components/pwa/PwaInstallPrompt.client.vue) component: this is shown on the right aside on wide screens, or at top on small screens. -On small screens, the PWA prompt for update will be shown as a button on the head, you can find it in [PwaBadge](https://github.com/elk-zone/elk/blob/main/components/pwa/PwaBadge.client.vue) component. +Nimbus uses prompt for update strategy, so the PWA prompt for update will be shown only if there is a new version of Nimbus available. -On wide screens, the PWA prompt for update will be shown as a prompt on the right aside, you can find it in [PwaPrompt](https://github.com/elk-zone/elk/blob/main/components/pwa/PwaPrompt.client.vue) component. +- On small screens, the PWA prompt for update is shown as a button on the head. You can find it in [`PwaBadge`](https://github.com/nimbus-town/nimbus/blob/main/components/pwa/PwaBadge.client.vue) component. +- On wide screens, the PWA prompt for update is shown as a prompt on the right aside. You can find it in [`PwaPrompt`](https://github.com/nimbus-town/nimbus/blob/main/components/pwa/PwaPrompt.client.vue) component. -PWA prompt for update will take preference over PWA installation prompt, so if there is a new version of Nimbus available, the PWA prompt for update will be shown instead of the PWA installation prompt. +PWA prompt for update takes preference over the PWA installation prompt. If there is a new version of Nimbus available, the PWA prompt for update will be shown instead of the PWA installation prompt. -All previous UI components don't have any logic, all them will use the logic provided by the [PWA plugin](https://github.com/elk-zone/elk/blob/main/modules/pwa/runtime/pwa-plugin.client.ts). +::alert{type="info"} +The UI components mentioned here don't contain any logic. They all use the logic provided by the [PWA plugin](https://github.com/nimbus-town/nimbus/blob/main/modules/pwa/runtime/pwa-plugin.client.ts). +:: ### Service Worker -You can find Nimbus custom service worker in [service-worker folder](https://github.com/elk-zone/elk/blob/main/service-worker), it provides: -- [Prompt for update strategy](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L14). -- [Web Push Notifications](https://github.com/elk-zone/elk/blob/main/service-worker/web-push-notifications.ts): [push notifications](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L105) and [push notification click](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L106). -- [Web Share Target API](https://github.com/elk-zone/elk/blob/main/service-worker/share-target.ts): [share target registration](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L107). +You can find Nimbus custom service worker in the [`service-worker` folder](https://github.com/nimbus-town/nimbus/blob/main/service-worker), it provides: + +- [Prompt for update strategy](https://github.com/nimbus-town/nimbus/blob/main/service-worker/sw.ts#L14). +- [Web Push Notifications](https://github.com/nimbus-town/nimbus/blob/main/service-worker/web-push-notifications.ts), [push notifications](https://github.com/nimbus-town/nimbus/blob/main/service-worker/sw.ts#L105) and [push notification click](https://github.com/nimbus-town/nimbus/blob/main/service-worker/sw.ts#L106). +- [Web Share Target API](https://github.com/nimbus-town/nimbus/blob/main/service-worker/share-target.ts) and [share target registration](https://github.com/nimbus-town/nimbus/blob/main/service-worker/sw.ts#L107). ### Push Notifications Subscription Logic -Nimbus will allow you to send push notifications to your users, you can find the logic for Web Push Notifications subscription [composables/push-notifications folder](https://github.com/elk-zone/elk/blob/main/composables/push-notifications). +Nimbus allows you to send push notifications to your users, you can find the logic for Web Push Notifications subscription in the [`composables/push-notifications` folder](https://github.com/nimbus-town/nimbus/blob/main/composables/push-notifications). -There is a limitation on browsers about registering multiple Web Push Notifications: you can only subscribe to one push service per browser per application: trying to register multiple push subscriptions will be treated as spam by the browser. +There is a limitation on browsers about registering multiple Web Push Notifications: you can only subscribe to one push service per browser per application. Trying to register multiple push subscriptions will be treated as spam by the browser. -If you try to register multiple push subscriptions, the browser will throw an error, and you will need to unregister the previous push subscription before registering a new one. +If you try to register multiple push subscriptions, the browser will throw an error. You need to unregister the previous push subscription before registering a new one. ### Debugging PWA in development -To debug the PWA in development, you will need to run `dev:pwa` or `dev:mocked:pwa` script. +To debug the PWA in development, you need to run `dev:pwa` or `dev:mocked:pwa` script. -Running one of previous scripts will start a development server with the PWA enabled: you can review the web manifests and debug the service worker in your browser, use any Chromium based browser, since we're registering the service worker using `type: 'module'`. +Running one of previous scripts starts a development server with the PWA enabled. You can review the web manifests and debug the service worker in your browser. Use any Chromium based browser, since we're registering the service worker using `type: 'module'`. -You can debug Web Push Notifications in desktop and mobile browser and Web Share Target in your mobile device, using the same URL as the development server. +You can debug Web Push Notifications in desktop and mobile browser and Web Share Target in your mobile device using the same URL as the development server. Right now, we can only debug on Android Chrome mobile browsers: -- Web Push Notifications: you don't need to install de PWA, just enable the notifications in the browser on notifications page or web push notifications settings page. + +- Web Push Notifications: you don't need to install the PWA. Just enable the notifications in the browser on notifications page or web push notifications settings page. - Web Share Target: you need to install the PWA, and then you can share content from other apps to Nimbus. ### Debugging PWA in mobile browsers -To debug the PWA service worker in your mobile browser, you will need to: -1) Enable development options in your Android device: +To debug the PWA service worker in your mobile browser, you need to: + +1. Enable development options in your Android device: - Go to "Settings" on your device. - Scroll down to "About phone" and tap it. - Locate the "Build number" and tap it repeatedly (usually 7 times) until you see a message saying that you have enabled developer options. - Go back to "Settings" and you should now see "Developer options" listed. - Tap on "Developer options" and you can enable various settings such as USB debugging, mock locations, and more. -2) Connect your Android device to your computer using a USB cable. -3) Enable USB debugging in your Android device: +2. Connect your Android device to your computer using a USB cable. +3. Enable USB debugging in your Android device: - Go to "Settings" on your device. - Scroll down to "Developer options" and tap it. - Enable "USB debugging". - Confirm the prompt on your device to allow USB debugging. - Open Chrome/Edge browser in your device. -4) Open Chrome on your computer and go to `chrome://inspect/#devices`. +4. Open Chrome on your computer and go to `chrome://inspect/#devices`. - Your device should be listed in the "Remote Target" section after a few seconds (if not, open Chrome/Edge and navigate to any page). - Click the "Port forwarding..." button and type "5314" into the "Port" input and "localhost:5314" into the "IP address and port" input, then press "Done". - Enter `http://localhost:5314` in the "Open tab with url" input and click the "Open" button. - Click on the "Inspect" button to open the DevTools. -5) Remember to remove the service worker from your device browser using dev tools once you finish testing the service worker: +5. Remember to remove the service worker from your device browser using dev tools once you finish testing the service worker: - Go to `Application > Storage`, you should check following checkboxes: - Application: `[x]` Unregister service worker - Storage: `[x]` Local and session storage `[x]` IndexedDB - Cache: `[x]` Cache storage and `[x]` Application cache - Click on Clear site data button - - Go to `Application > Service Workers` and check the current service worker is missing or has the status deleted or reduntant. -6) Disable port forwarding: open the "Port forwarding..." modal again on the `chrome://inspect/#devices` page and either uncheck the "Enable port forwarding" option or remove the entry from the list and click "Done". + - Go to `Application > Service Workers` and check the current service worker is missing or has the status deleted or redundant. +6. Disable port forwarding: open the "Port forwarding..." modal again on the `chrome://inspect/#devices` page and either uncheck the "Enable port forwarding" option or remove the entry from the list and click "Done". + +