{"section":"tutorials","requestedLocale":"en","requestedSlug":"how-to-turn-my-store-website-into-a-pwa","locale":"en","slug":"how-to-turn-my-store-website-into-a-pwa","path":"docs/en/tutorials/storefront/layout/how-to-turn-my-store-website-into-a-pwa.md","branch":"main","content":"> ℹ️ This article is only valid for stores using CMS Portal (Legacy).\n\nA Progressive Web App (PWA) is a set of techniques for developing web applications that add features previously restricted to native applications.\n\n- **Progressive:** Works in any browser.\n- **Responsive:** Adapts to any device, whether desktop, tablet, or mobile.\n- **Connection-independent:** Works even when the user is offline.\n- **App-like experience:** Provides a user experience comparable to native applications.\n- **Updated:** No need to download any updates, as the Service Worker allows the browser to automatically detect and update when needed.\n- **Safe:** Requires HTTPS connection.\n- **Engaging:** Allows push notifications to interact with the user.\n- **Installable:** You can add an icon to the main screen of your mobile device without accessing an app store.\n- **Shareable:** Sharing is facilitated through URL, without complex installation.\n\nIf you already have a website or web application, you can gradually implement the features that define a PWA, such as notifications, file caching, offline execution, and other options that make users feel like they're using a native application.\n\n> ⚠️ VTEX **doesn't** offer native solutions for conversion to PWA in the CMS Portal (Legacy). VTEX, however, provides the basic infrastructure for manual implementation. Stores developed with the VTEX IO Store Framework have this feature natively.\n\n## Instructions\n\n### Create the manifest.json file\n\nThe web application's `manifest.json` file provides information about an application (such as name, author, icon, and description) in a JSON text file. This file enables a web application to be installed on a smartphone.\n\nTo create the JSON, follow the steps below:\n\n1. In the VTEX Admin, go to **Store Settings > Storefront > Checkout**.\n2. Click the gear icon ⚙️ for the desired site.\n3. In the `Code` tab, click `New`.\n4. Choose the `File` option.\n5. In **File name** field, type `manifest.json`.\n6. Enter the application details (such as name, icon, and description), as shown in the example below:\n\n ```json\n {\n \"name\": \"My Store\",\n \"short_name\": \"Store\",\n \"start_url\": \"/\",\n \"display\": \"standalone\",\n \"background_color\": \"#fff\",\n \"theme_color\": \"#2F3DB2\",\n \"icons\": [{\n \t\"src\": \"/arquivos/icon.png\",\n \t\"sizes\": \"192x192\",\n \t\"type\": \"image/png\"\n }]\n }\n ```\n\n7. Click `Save`.\n\n> ℹ️ **Tip:** Use icons in a minimum resolution of 192x192px and format hexadecimal colors following your visual identity.\n\n### Add the `manifest.json` file to the web application\n\nAfter creating the `manifest.json` file, add the following line inside the `` section of your `index.html` file:\n\n```\n\n```\n\nWith this, your web application will be able to open a splash screen like native applications.\n\n### Create a Service Worker\n\nService Worker is a script that your browser runs in the background, separate from the web. It enables features such as periodic syncs, push notifications, and offline execution.\n\nTo create the script, follow the steps below:\n\n1. In the VTEX Admin, go to **Store Settings > Storefront > Checkout**.\n2. Click the gear icon ⚙️ for the desired website.\n3. In the `Code` tab, click `New`.\n4. Choose the `File` option.\n5. In the **File name** field, type `service-worker.js`.\n6. Implement the feature as in the example below:\n\n ```js\n // --- CACHE SETTINGS ---\n // Defines the cache version to facilitate future updates\n\n const CACHE = 'cache-v1';\n\n // List of critical resources for pre-caching (pages, CSS, images)\n const FILES = ['/', '/files/main.css', '/files/logo.jpg'];\n\n // --- INSTALLATION EVENT ---\n // Executed once when the Service Worker is registered\n\n self.addEventListener('install', (e) => {\n // Opens the cache and stores the defined resources\n e.waitUntil(caches.open(CACHE).then(cache => cache.addAll(FILES)));\n });\n\n // --- FETCH EVENT ---\n // Intercepts all network requests on the page\n\n self.addEventListener('fetch', (e) => {\n // Cache-first strategy:\n // 1. Tries to respond using cache resources.\n // 2. If not found, fetches from the network.\n\n e.respondWith(caches.match(e.request).then(res => res || fetch(e.request)));\n });\n ```\n\n7. Click **Save**.\n\nAlthough the file is in `/files/service-worker.js`, it receives the header `Service-Worker-Allowed` with the value `/`, allowing to intercept requests from the site's root.\n\n> ⚠️ **Warning:** The Service Worker will only work in HTTPS environments. Always test in production or use secure tunnels in development.\n\nTo learn more about service workers, see Google [Web Fundamentals](https://developers.google.com/web/fundamentals/primers/service-workers/) documentation.\n\n### Check your PWA implementation\n\nTo ensure that your site is on the right track when building your PWA, use inspection tools such as Google's Lighthouse.\n\nTo inspect your site using Lighthouse, follow the steps below:\n\n1. Download the Lighthouse extension in your browser.\n2. Go to your store website.\n3. Click the tool widget.\n4. Please wait for the analysis and view the generated result.\n\nTo learn more, see the VTEX Developer Portal guide [Getting started with Lighthouse](https://developers.vtex.com/docs/guides/storefront-getting-started-with-lighthouse)."}