{"id":16212490,"url":"https://github.com/temzasse/vite-plugin-splash-screen","last_synced_at":"2025-04-02T21:31:03.774Z","repository":{"id":229371516,"uuid":"776557369","full_name":"Temzasse/vite-plugin-splash-screen","owner":"Temzasse","description":"Vite plugin for adding a splash screen to your app 💦📱","archived":false,"fork":false,"pushed_at":"2025-03-10T12:46:35.000Z","size":446,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-17T17:11:21.293Z","etag":null,"topics":["react","splash-screen","svelte","vite","vite-plugin","vue"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Temzasse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-23T20:44:44.000Z","updated_at":"2025-03-10T12:46:39.000Z","dependencies_parsed_at":"2024-03-23T22:21:38.578Z","dependency_job_id":"0cb8d049-192c-43bd-b232-e10cd0bcb66f","html_url":"https://github.com/Temzasse/vite-plugin-splash-screen","commit_stats":null,"previous_names":["temzasse/vite-plugin-splash-screen"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Temzasse%2Fvite-plugin-splash-screen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Temzasse%2Fvite-plugin-splash-screen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Temzasse%2Fvite-plugin-splash-screen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Temzasse%2Fvite-plugin-splash-screen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Temzasse","download_url":"https://codeload.github.com/Temzasse/vite-plugin-splash-screen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246895679,"owners_count":20851310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["react","splash-screen","svelte","vite","vite-plugin","vue"],"created_at":"2024-10-10T10:52:38.010Z","updated_at":"2025-04-02T21:31:03.768Z","avatar_url":"https://github.com/Temzasse.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align='center'\u003evite-plugin-splash-screen\u003c/h1\u003e\n\n\u003cdiv align=\"center\" \u003e\n  \u0026middot;\n  \u003ci\u003eFramework-agnostic splash screen plugin for Vite\u003c/i\u003e\n  \u0026middot;\n  \u003cbr/\u003e\n  \u003cbr/\u003e\n  \u003cimg alt=\"npm version\" src=\"https://img.shields.io/npm/v/vite-plugin-splash-screen?style=for-the-badge\"\u003e\n  \u003cimg alt=\"npm license\" src=\"https://img.shields.io/npm/l/vite-plugin-splash-screen?style=for-the-badge\"\u003e\n  \u003cbr/\u003e\n  \u003cbr/\u003e\n\u003c/div\u003e\n\n![Demo of vite-plugin-splash-screen with line style loading indicator](media/demo-1.gif)\n\n## 💦 Features\n\nWhen building a Single-Page-Application (SPA) that is fully rendered on the client side (CSR), it is common to only send a minimal HTML file to the client which only defines a single div as the root of the app and includes links and scripts to load all the necessary assets to render the application.\n\nThis common approach will lead to a blank screen for a few seconds while the JS is being loaded and parsed. To improve the user experience we can add a splash screen, which are commonly used in mobile applications, that is displayed while the assets are being loaded and parsed. Then when your application is ready and initialized, the splash screen can be animated out of the way to reveal the application.\n\nWith `vite-plugin-splash-screen` you get the following:\n\n- **🤹 Framework-agnostic**: Works with any frontend framework that uses Vite!\n- **🎨 Customizable**: You can customize the splash screen with your own logo, change colors, and display a loading indicator.\n- **🚀 Fast**: The splash screen is inlined to the HTML file at build time.\n- **🕹️ Full control**: You can control when the splash screen is hidden.\n- **🔮 Easy to use**: Just add the plugin to your Vite config and you are good to go.\n\n## 📲 Installation\n\nInstall `vite-plugin-splash-screen` with your favorite package manager:\n\n```sh\nnpm install -D vite-plugin-splash-screen\n\n# yarn\nyarn add -D vite-plugin-splash-screen\n\n# pnpm\npnpm add -D vite-plugin-splash-screen\n```\n\n## 🧑‍💻 Usage\n\nImport the plugin and add it to you Vite config.\n\nThe only required option is `logoSrc`, which is the path (relative to the [publicDir](https://vitejs.dev/config/shared-options.html#publicdir)) of the logo that will be displayed on the splash screen.\n\n```js\nimport { splashScreen } from \"vite-plugin-splash-screen\";\n\nexport default defineConfig({\n  plugins: [\n    /* ...other plugins... */\n    splashScreen({\n      logoSrc: \"logo.svg\",\n    }),\n  ],\n});\n```\n\n\u003e [!IMPORTANT]  \n\u003e **Only SVG logos are supported at the moment so that the logo can be inlined to the HTML file**.\n\u003e\n\u003e Make sure the logo has appropriate dimensions and is optimized for the web. See [SVGOMG](https://jakearchibald.github.io/svgomg/) for optimizing SVG files.\n\nThen in your application code (written in React, Vue, Svelte, whatever), you can hide the splash screen when the application is ready.\n\n```js\nimport { hideSplashScreen } from \"vite-plugin-splash-screen/runtime\";\n\nhideSplashScreen();\n```\n\nFor example in a React app, you can hide the splash screen in the `useEffect` hook.\n\n```jsx\nimport { useEffect } from \"react\";\nimport { hideSplashScreen } from \"vite-plugin-splash-screen/runtime\";\n\nexport function App() {\n  useEffect(() =\u003e {\n    hideSplashScreen();\n  }, []);\n\n  return \u003cdiv\u003eMy App\u003c/div\u003e;\n}\n```\n\n\u003e [!TIP]\n\u003e You should wait until your application is fully initialized before hiding the splash screen. This could include setting up a router, initializing a store, loading translations, authenticating the user, or loading data from an API etc.\n\n## 🎨 Customization\n\nYou can customize the splash screen by providing additional options to the plugin.\n\n### `minDurationMs`\n\nThe minimum duration the splash screen should be displayed, even if the `hideSplashScreen` function has been called.\nThis is useful to prevent the splash screen from flickering in case the app is initialized very quickly.\n\nFor example, to display the splash screen for at least 2 seconds:\n\n```js\nsplashScreen({\n  logoSrc: \"logo.svg\",\n  minDurationMs: 2000,\n});\n```\n\n### `loaderType`\n\nWhat type of loading indicator should be displayed below the logo.\n\nAvailable options: `\"line\"` (default), `\"dots\"`, `\"none\"`.\n\nWith `\"dots\"` you get the following loading indicator:\n\n```js\nsplashScreen({\n  logoSrc: \"logo.svg\",\n  loaderType: \"dots\",\n});\n```\n\n![Demo of vite-plugin-splash-screen with dots style loading indicator](media/demo-2.gif)\n\nProvide `\"none\"` to hide the loading indicator:\n\n```js\nsplashScreen({\n  logoSrc: \"logo.svg\",\n  loaderType: \"none\",\n});\n```\n\n![Demo of vite-plugin-splash-screen with no loading indicator](media/demo-3.gif)\n\n### `loaderBg`\n\nThe background color of the loading indicator (default `#0072f5`).\n\nExample:\n\n```js\nsplashScreen({\n  logoSrc: \"logo.svg\",\n  loaderType: \"line\",\n  loaderBg: \"#ff0000\",\n});\n```\n\n### `splashBg`\n\nThe background color of the splash screen (default `#ffffff`).\n\nExample:\n\n```js\nsplashScreen({\n  logoSrc: \"logo.svg\",\n  splashBg: \"#000000\",\n});\n```\n\n### Dynamic colors\n\nIf your app supports theming (eg. light and dark mode), you can dynamically change the colors of the splash screen using CSS variables.\n\nThe following CSS variables are available:\n\n- `--vpss-bg-splash` - Splash screen background color (default `#ffffff`)\n- `--vpss-bg-loader` - Loading indicator background color (default `#0072f5`)\n\n⚠️ Note: in order to avoid flickering of colors you should set the CSS variables **before** the splash screen is rendered! You can easily achieve this by utilizing the [vite-plugin-color-scheme](https://github.com/Temzasse/vite-plugin-color-scheme) plugin to inline a small script to setup the CSS variables based on the user's preferred color scheme.\n\n```js\n// vite.config.ts\nimport { splashScreen } from \"vite-plugin-splash-screen\";\nimport { colorScheme } from \"vite-plugin-color-scheme\";\n\nexport default defineConfig({\n  plugins: [\n    colorScheme({\n      defaultScheme: \"light\",\n      variables: {\n        light: {\n          \"--vpss-bg-splash\": \"#ffffff\",\n          \"--vpss-bg-loader\": \"#b18500\",\n        },\n        dark: {\n          \"--vpss-bg-splash\": \"#242424\",\n          \"--vpss-bg-loader\": \"#ffcb29\",\n        },\n      },\n    }),\n    splashScreen({\n      /* ...your options... */\n    }),\n  ],\n});\n```\n\n## 🛠️ Advanced usage\n\n### Prevent showing splash screen with URL search parameter\n\nIn some cases you might want to prevent the splash screen from being displayed,\neg. if you need to manually trigger a page refresh in your application code after\nthe splash screen has been hidden. For example when the user changes the language\nand you need to reload the page to apply the new translations, or when the user\nswitches workspaces in your application.\n\nIn these cases it is probably better to not show the splash screen even though\ntechnically the app is being initialized from scratch again as the user has\nalready seen the splash screen once.\n\nYou can prevent the splash screen from being displayed by adding a URL search\nparameter to the URL before reloading the page.\n\n```tsx\nconst params = new URLSearchParams(location.search);\nparams.set(\"vpss\", \"false\");\nwindow.location.search = params.toString();\n```\n\nThe added search parameter will be automatically removed by the plugin when\nthe splash screen is initialized after the page reload, so you don't need to\nremove it manually yourself.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftemzasse%2Fvite-plugin-splash-screen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftemzasse%2Fvite-plugin-splash-screen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftemzasse%2Fvite-plugin-splash-screen/lists"}