{"id":27933188,"url":"https://github.com/anicine/native_splash_screen","last_synced_at":"2026-04-17T15:33:15.070Z","repository":{"id":291650033,"uuid":"977188972","full_name":"anicine/native_splash_screen","owner":"anicine","description":"WIP simple package to let your app show a splash screen before it loads completely.","archived":false,"fork":false,"pushed_at":"2025-10-03T12:15:03.000Z","size":38997,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T19:34:20.426Z","etag":null,"topics":["dart","flutter","linux","windows"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/native_splash_screen","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anicine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-03T16:15:46.000Z","updated_at":"2026-02-20T08:31:06.000Z","dependencies_parsed_at":"2025-07-05T15:52:31.147Z","dependency_job_id":null,"html_url":"https://github.com/anicine/native_splash_screen","commit_stats":null,"previous_names":["anicine/native_splash_screen"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/anicine/native_splash_screen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anicine%2Fnative_splash_screen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anicine%2Fnative_splash_screen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anicine%2Fnative_splash_screen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anicine%2Fnative_splash_screen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anicine","download_url":"https://codeload.github.com/anicine/native_splash_screen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anicine%2Fnative_splash_screen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31934344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T12:37:54.787Z","status":"ssl_error","status_checked_at":"2026-04-17T12:37:25.095Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["dart","flutter","linux","windows"],"created_at":"2025-05-07T04:27:47.303Z","updated_at":"2026-04-17T15:33:15.063Z","avatar_url":"https://github.com/anicine.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🖼️ native_splash_screen\n\n\u003e Native splash screens provide faster startup visuals, smoother transitions, and eliminate the first-frame jank common with typical Flutter splash workarounds.\n\n**native_splash_screen** is a Flutter plugin that delivers fully configurable, animated splash screens on **Linux**, **Windows** and **Macos** — powered by **GTK + Cairo**, **Win32 GDI** and **AppKit + Cocoa**, respectively.\n\n\u003e 🔧 Image composition and layout are handled at **compile-time** via a CLI tool, while rendering is performed natively at runtime using high-performance platform APIs.\n\n## 📚 Table of Contents\n\n- [✨ Features](#-features)\n- [📦 Installation](#-installation)\n- [⚙️ Setup](#️-setup)\n  - [1. Generate the splash screen configuration file](#1-generate-the-splash-screen-configuration-file)\n  - [2. Generate the splash screen build files](#2-generate-platform-specific-buildintegration-files)\n  - [3. Generate the splash screen code](#3-generate-the-splash-screen-code)\n  - [4. Integrate the build files](#4-integrate-the-build-files)\n    - [🐧 Linux](#-linux)\n    - [🪟 Windows](#-windows)\n    - [🍎 Macos](#-macos)\n  - [5. Add the missing code on each platform](#5-add-the-missing-code-on-each-platform)\n    - [🐧 Linux](#-linux-1)\n    - [🪟 Windows](#-windows-1)\n    - [🍎 Macos](#-macos-1)\n- [🚀 Usage](#-usage)\n- [🍎 macOS Configuration Notes](#-macos-configuration-notes)\n- [🛠️ How It Works](#️-how-it-works)\n- [📝 Configuration](#-configuration)\n- [🎥 Demos](#-demos)\n- [📄 License](#-license)\n\n---\n\n## ✨ Features\n\n- 🖼️ Native splash screens on Linux (GTK + Cairo) and Windows (WinGDI) and Macos (AppKit + Cocoa)\n-  🖥️ Retina Display Support: Automatically generates 1x and 2x assets for macOS, ensuring crystal-clear splash screens on all displays.\n- 🎞️ Runtime closing animations e.g : fading\n- ⚙️ CLI-driven image layout and asset generation\n- 🧩 Static linking — zero runtime dependencies\n- 🛠️ Easily extensible for other platforms\n- 🌟 Supports raster formats like PNG and JPEG. Transparency and scaling are fully handled at compile time by the CLI.\n---\n\n## 📦 Installation\n\nAdd `native_splash_screen` to your `pubspec.yaml`:\n\n```yaml\ndependencies:\n  native_splash_screen: ^3.0.0\n```\n\nAlso add the CLI tool under dev_dependencies:\n\n```yaml\ndev_dependencies:\n  native_splash_screen_cli: ^3.0.0\n```\n\n\u003e ⚠️ **Caution:** To avoid errors, ensure `native_splash_screen` and `native_splash_screen_cli` are on the same major version (e.g., `3.x.x`). The runtime and CLI tool are designed to work together.\n\nThen run:\n\n```sh\nflutter pub get\n```\n\n## ⚙️ Setup\n\nSetting up `native_splash_screen` involves a few steps: generating configuration, integrating platform-specific build files, and adding minimal native code to show the splash screen early.\n\n## 1. Generate the splash screen configuration file\n\nFirst, generate the main YAML configuration file (`native_splash_screen.yaml`) in your project's root directory. This file allows you to customize the splash screen's appearance and behavior for each platform.\n\nRun:\n\n```sh\ndart run native_splash_screen_cli init\n```\n\n- This command will create `native_splash_screen.yaml` pre-filled with comments and examples to guide you through the available options.\n\n## 2. Generate platform-specific build/integration files\n\nOnce you've configured `native_splash_screen.yaml` (e.g., enabled desired platforms, set image paths), run the setup command. This prepares platform-specific files that help integrate the splash screen into your native builds.\n\nRun:\n\n```sh\ndart run native_splash_screen_cli setup\n```\n\n- For Linux and Windows: This typically creates `native_splash_screen.cmake` files in your respective platform runner directories (`linux/runner` and `windows/runner`). These CMake files define how the native splash screen code (generated in the next step) will be compiled and linked.\n\n- For macOS: This step primarily prepares the ground. The actual Swift configuration files are generated by the gen command (see next step), and integration involves Xcode project modifications.\n\n## 3. Generate the splash screen code\n\nNow make sure to add the images path in the configuration file\nand put a valid window size and image size.\n\nThen you can generate the splash screen code by running:\n\n```sh\ndart run native_splash_screen_cli gen\n```\n\nThis command:\n- Reads your `native_splash_screen.yaml`.\n- Processes the specified images (resizing, applying effects as configured).\n- Generates the actual native source code for the splash screen:\n    - **Linux \u0026 Windows:** Creates C++ source files that are then compiled via the `.cmake` files.\n    - **macOS:** Creates Swift files (`NativeSplashScreen.swift` and its flavor-specific counterparts like `NativeSplashScreen_Debug.swift`) in your `macos/Runner/` directory. These files contain your splash screen configuration as Swift code.\n\n\u003e **Important:** Do not run your app yet. You still need to integrate these generated files and add platform-specific initialization code as described below.\n\n## 4. Integrate the build files\n\nNow, you need to tell each platform's build system how to use the files generated in the previous steps.\n\n### 🐧 Linux\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick to Expand\u003c/strong\u003e\u003c/summary\u003e\n\nApply the following patch to your `linux/runner/CMakeLists.txt`:\n\n\u003e if you edited the linux path in `native_splash_screen.yaml`, you\n\u003e need to apply the patch in to the **correct** CMakefile.txt \n\n```diff\n+ # Include splash screen library configuration\n+ include(\"${CMAKE_CURRENT_SOURCE_DIR}/native_splash_screen.cmake\")\n\n  add_executable(${BINARY_NAME}\n          \"main.cc\"\n          \"my_application.cc\"\n          \"${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc\"\n  )\n```\n\u003c/details\u003e\n\n### 🪟 Windows\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick to Expand\u003c/strong\u003e\u003c/summary\u003e\n\nApply the following patch to your `windows/runner/CMakeLists.txt`:\n\n\u003e if you edited the windows path in `native_splash_screen.yaml`, you\n\u003e need to apply the patch in to the **correct** CMakefile.txt \n\n```diff\n+ # Include splash screen library configuration\n+ include(\"${CMAKE_CURRENT_SOURCE_DIR}/native_splash_screen.cmake\")\n\n  add_executable(${BINARY_NAME} WIN32\n    \"flutter_window.cpp\"\n    \"main.cpp\"\n    \"utils.cpp\"\n    \"win32_window.cpp\"\n    \"${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc\"\n    \"Runner.rc\"\n    \"runner.exe.manifest\"\n  )\n```\n\u003c/details\u003e\n\n### 🍎 Macos\n\n\u003e **Xcode is required** for macos setup. \n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick to Expand\u003c/strong\u003e\u003c/summary\u003e\n\nFor macOS, integration involves adding the Swift files generated by `native_splash_screen_cli gen` to your Xcode project and setting a compilation flag. **Xcode is required for these steps.**\n\n**A. Add Generated Swift Files to `Runner` Target:**\n\nThe `gen` command creates these files in `[YourApp]/macos/Runner/`:\n- `NativeSplashScreen.swift`\n- `NativeSplashScreen_Debug.swift`\n- `NativeSplashScreen_Profile.swift`\n- `NativeSplashScreen_Release.swift`\n\nFollow these visual steps to add them to Xcode:\n\n**1** - click on **`01`** then **`02`**.\n![step 01](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/macos-setup-01.png)\n\n**2** - then click on **`03`**.\n![step 02](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/macos-setup-02.png)\n\n**3** - then search for `swift compiler - custom flags` on **`04`**.\n![step 03](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/macos-setup-03.png)\n\n**4** - click `↵` in **`05`** and type `PROFILE` then click `↵` to confirm and click **`06`**.\n![step 04](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/macos-setup-04.png)\n\n**5** - click **`07`** to expand it then click **`08`** to add new files.\n![step 05](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/macos-setup-05.png)\n\n**6** - click **`09`** to choose the files.\n![step 06](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/macos-setup-06.png)\n\n**7** - in the project root folder open the macos folder like **`10`** then open the Runner folder like **`11`** after that choose all the swift files which contain **\"NativeSplashScreen\"** like **`12`**, cause those get generated by the `native_splash_screen_cli` the click open like **`13`**.\n![step 07](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/macos-setup-07.png)\n\n**8** - finally click finish like **`14`** .\n![step 08](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/macos-setup-08.png)\n\n\u003c/details\u003e\n\n## 5. Add the missing code on each platform\n\n### 🐧 Linux\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick to Expand\u003c/strong\u003e\u003c/summary\u003e\n\nApply the following patch to your `linux/runner/main.cc`:\n\n```diff\n+#include \u003cnative_splash_screen_linux/native_splash_screen_linux_plugin.h\u003e\n#include \"my_application.h\"\n\nint main(int argc, char** argv) {\n    // Initialize GTK first\n+    gtk_init(\u0026argc, \u0026argv);\n\n    // So can safely show the splash screen first.\n+    show_splash_screen();\n\n    // Then initialize and run the application as normal\n    g_autoptr(MyApplication) app = my_application_new();\n    return g_application_run(G_APPLICATION(app), argc, argv);\n}\n```\n\u003c/details\u003e\n\n### 🪟 Windows\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick to Expand\u003c/strong\u003e\u003c/summary\u003e\n\nApply the following patch to your `windows/runner/main.cpp`:\n\n```diff\n+#include \u003cnative_splash_screen_windows/native_splash_screen_windows_plugin_c_api.h\u003e\n\n#include \"flutter_window.h\"\n#include \"utils.h\"\n\nint APIENTRY wWinMain(_In_ HINSTANCE instance, _In_opt_ HINSTANCE prev,\n                      _In_ wchar_t *command_line, _In_ int show_command) {\n   // Show the splash screen first.\n+  ShowSplashScreen();\n\n```\n\u003c/details\u003e\n\n### 🍎 Macos\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick to Expand\u003c/strong\u003e\u003c/summary\u003e\n\nApply the following patch to your `macos/Runner/AppDelegate.swift`:\n\n```diff\nimport Cocoa\nimport FlutterMacOS\n+import native_splash_screen_macos\n\n@main\nclass AppDelegate: FlutterAppDelegate {\n    override func applicationShouldTerminateAfterLastWindowClosed(_ sender: NSApplication) -\u003e Bool {\n        return true\n    }\n\n    override func applicationSupportsSecureRestorableState(_ app: NSApplication) -\u003e Bool {\n        return true\n    }\n+\n+    override func applicationWillFinishLaunching(_ notification: Notification) {\n+        NativeSplashScreen.configurationProvider = NativeSplashScreenConfiguration()\n+        NativeSplashScreen.show()\n+    }\n}\n\n```\n\n\u003c/details\u003e\n\n## 🚀 Usage\n\n### Run\n\nIf everything completes successfully, you can now run and test your app.\nIf you encounter any issues during generation, please [open an issue](https://github.com/anicine/native_splash_screen/issues).\n\n### Closing the splash screen\n\nSo now you need to close the splash screen in your app when you're ready:\n```dart\nimport 'package:flutter/material.dart';\nimport 'package:native_splash_screen/native_splash_screen.dart' as nss;\n\nvoid main() {\n  WidgetsFlutterBinding.ensureInitialized();\n  runApp(const MyApp());\n}\n\nclass MyApp extends StatefulWidget {\n  const MyApp({super.key});\n\n  @override\n  State\u003cMyApp\u003e createState() =\u003e _MyAppState();\n}\n\nclass _MyAppState extends State\u003cMyApp\u003e {\n  @override\n  void initState() {\n    super.initState();\n    // Close splash screen after the first frame renders\n    WidgetsBinding.instance.addPostFrameCallback((_) {\n      nss.close(animation: nss.CloseAnimation.fade);\n    });\n  }\n\n  @override\n  Widget build(BuildContext context) {\n    return MaterialApp(\n      home: Scaffold(\n        appBar: AppBar(title: const Text('Native Splash Screen')),\n      ),\n    );\n  }\n}\n```\n\n\u003e💡 Calling `close()` multiple times or when the splash screen is already closed has no effect and is completely safe.\n\nSee the [example app](https://github.com/anicine/native_splash_screen/tree/main/native_splash_screen/example) for more details.\n\n## 🍎 macOS Configuration Notes\n\nThe package automatically generates assets for both standard (1x) and high-resolution Retina (2x) displays to ensure your splash screen looks sharp on all devices.\n\n#### Quality Recommendation for Retina Displays\n\nFor the best visual quality, your source image in `image_path` should have pixel dimensions that are at least **twice** the configured `image_width` and `image_height`.\n\n\u003e **Example**: For an `image_width` of 400 and `image_height` of 200, provide a source image that is at least **800x400 pixels**.\n\n#### How `image_scaling` works on macOS\n\nThe scaling logic is designed to prevent quality loss.\n\n-   **`image_scaling: false` (Default)**: Prevents a small source image from being upscaled (stretched), which causes blurriness. If the image is smaller than the target dimensions, it will be centered on the splash screen at its original size. Large images will still be cleanly downscaled to fit.\n\n-   **`image_scaling: true`**: Forces the image to be resized to exactly match the configured `image_width` and `image_height`, whether it's upscaling or downscaling.\n\n## 🛠️ How It Works\n\n**At compile time (`gen`):**\n- Parses your YAML configuration\n- Composes and rasterize your image layout\n- Generates native C++ an swift source code\n- Builds platform-specific static libraries (Linux and Windows)\n\n**At runtime:**\n- **Linux**: Uses GTK \u0026 Cairo to render the splash screen.\n- **Windows**: Uses Win32 GDI for fast native rendering.\n- **Macos**: Uses AppKit \u0026 Cocoa to render the splash screen.\n\n- You call `close()` from Dart when your app is ready, triggering the animation.\n\n## 📝 Configuration\n\nSee [native_splash_screen_cli](https://pub.dev/packages/native_splash_screen_cli) for configuration reference.\n\n## 🎥 Demos\n\nHere are some recorded demos of the splash screen in different environments:\n\n### 🐧 Hyprland (Wayland)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick to Expand\u003c/strong\u003e\u003c/summary\u003e\n\n![Hyprland Demo](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/nss-hyprland.gif)\n\n\u003e ⚠️ Note: Most Wayland window managers — especially tiling WMs like Hyprland — are very strict about client-side window movement.  \n\u003e Because of this, only the **fade** animation is supported reliably. Slide or Move transitions may not behave as expected.\n\n\u003c/details\u003e\n\n### 🐧 Linux Mint (X11)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick to Expand\u003c/strong\u003e\u003c/summary\u003e\n\n![Mint Demo](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/nss-mint.gif)\n\n\u003c/details\u003e\n\n### 🪟 Windows\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick to Expand\u003c/strong\u003e\u003c/summary\u003e\n\n![Windows Demo](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/nss-windows.gif)\n\n\u003c/details\u003e\n\n### 🍎 Macos\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick to Expand\u003c/strong\u003e\u003c/summary\u003e\n\n![Macos Demo](https://raw.githubusercontent.com/anicine/native_splash_screen/refs/heads/main/resources/nss-macos.gif)\n\n\u003c/details\u003e\n\n## 📄 License\n\n```\nBSD 3-Clause License\n\nCopyright (c) 2025, Anicine Project\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n1. Redistributions of source code must retain the above copyright notice, this\n   list of conditions and the following disclaimer.\n\n2. Redistributions in binary form must reproduce the above copyright notice,\n   this list of conditions and the following disclaimer in the documentation\n   and/or other materials provided with the distribution.\n\n3. Neither the name of the copyright holder nor the names of its\n   contributors may be used to endorse or promote products derived from\n   this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanicine%2Fnative_splash_screen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanicine%2Fnative_splash_screen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanicine%2Fnative_splash_screen/lists"}