└── README.md /README.md: -------------------------------------------------------------------------------- 1 | **⚠️ Important notice:** Our application for the GSoC 2025 program wasn't approved, so we won't be participating in GSoC 2025. We'll apply again for the next year's program. Thanks so much to everyone who contributed Neutralinojs before the GSoC program announced approved organizations. 2 | 3 | # GSoC 2025 - Neutralinojs 4 | 5 | Google Summer of Code 2025 ideas and guidelines - Neutralinojs 6 | 7 | ## What is GSoC? 8 | 9 | GSoC (Google Summer of Code) is an international program that motivates developers to contribute to open-source projects. Google awards stipends for contributors who 10 | successfully complete the GSoC program. GSoC contributors typically work on open-source development tasks under the guidance of organization mentors. Read more details about GSoC from the [official website](https://summerofcode.withgoogle.com/). 11 | 12 | ## How do you become a GSoC contributor? 13 | 14 | Anyone (including beginners and students) older than 18 can contribute to the GSoC program. Check more details about contributor eligibility from [this link](https://summerofcode.withgoogle.com/rules). 15 | 16 | Follow these steps to get started with GSoC 2025 as a contributor: 17 | 18 | 1. Understand Neutralinojs as a user (app developer) using the [official website](https://neutralino.js.org). 19 | 2. Create a sample Neutralinojs app using several native API functions. 20 | 3. Join the Neutralinojs Discord channel using [this invitation link](https://discord.gg/cybpp4guTJ). 21 | 4. Introduce yourself in the #gsoc channel on Discord and post the GitHub link of your sample app. 22 | 5. Become familiar with the main project and sub-projects, start with the [documentation](https://neutralino.js.org/docs), and then [codebases](https://github.com/neutralinojs). 23 | 6. Watch [framework](https://youtu.be/QGZywYDsSyg), [JavaScript API](https://youtu.be/V-RD6ia5YjY), and [CLI](https://youtu.be/XUj20aJDJiI) code explanation videos for detailed codebase explanations. 24 | 7. Read both [contribution guide](https://neutralino.js.org/docs/contributing/framework-developer-guide) and [code style guide](https://neutralino.js.org/docs/contributing/code-style-guide), then start contributing (our recommendation is to start contributing to documentation first to master the Neutralinojs framework as a user). 25 | 8. Tell us about tasks that you would like to work on. If you have new ideas, mention them in community channels including your project goals. 26 | 9. Start drafting a proposal by discussing it with mentors. 27 | 10. Submit your proposal and achieve the planned milestones based on the GSoC program [schedule](https://summerofcode.withgoogle.com/programs/2025). 28 | 29 | **⚠️ Important notice:** Mastering a codebase takes time even if you are so experienced in languages and tools used within the specific codebase. Neutralinojs codebases use several unique techniques, practices, and standards to implement simple solutions for complex problems — understanding them properly takes time. So, we recommend you to get started by making small but high-quality contributions like bug fixes, code improvements, and small features first without trying to implement entire APIs or big features. Also, make sure not to implement solutions for existing GSoC ideas during the contribution period since our goal is to build well-designed solutions for them collaboratively during the actual GSoC coding period based on approved GSoC proposals. 30 | 31 | ## How do you start writing a project proposal? 32 | 33 | 1. Make sure to follow the above initial steps and become familiar with the project. 34 | 2. Select a project idea out of the mentioned below 35 | 3. If you have an idea of your own / want to initiate one, post its summary and goals in a [new GitHub discussion thread](https://github.com/neutralinojs/gsoc2025/discussions/new?category=ideas). 36 | 4. Wait until project maintainers give feedback to the post (We can identify possible changes in the early stage). 37 | 5. Start drafting your proposal based on the Neutralinojs GSoC contributor proposal outline. 38 | 39 | ## What is the project proposal template? 40 | 41 | Please create your GSoC proposal according to the following outline: 42 | 43 | 1. Contact details (Name, Country, Email, GitHub username, Discord username, and a small description about yourself) 44 | 2. Neutralinojs experience (Explain your familiarity with Neutralinojs)4 45 | 3. Contributions (Add links to your pull requests, issues, and discussion threads) 46 | 4. Project description (Describe the project idea) 47 | 5. Goals (Summary of deliverables) 48 | 6. Tasks Timeline (Divide your goals into tasks and map with the GSoC timeline) 49 | 7. Future contributions (How do you plan to contribute to Neutralinojs in the future?) 50 | 51 | ## GSoC 2025 project ideas 52 | 53 | We have listed down some crucial tasks below for you. But, feel free to discuss 54 | your own ideas with us via [Discord](https://discord.gg/cybpp4guTJ) or email (`neutralinojs[AT]gmail.com`) or create a GitHub discussion thread. You can contribute Neutralinojs framework, CLI, client library and templates. 55 | 56 | Thank you for contributing to open-source 🎉 57 | 58 | ### Neutralinojs builder: a CLI plugin to generate platform-specific app installers 59 | 60 | Neutralinojs CLI generates platform-specific binaries for Linux, macOS, and Windows with a platform-independent resource file. Neutralinojs application developers currently should use various tools to create application installers (i.e.,: AppImage, NSIS) for each operating system. However, we have no plans to add application installer generation support directly to the neu CLI codebase to keep the CLI implementation minimal and less platform-dependent. So, we would like to implement the platform-specific installer generator as a plugin for the official CLI within the official Neutralinojs GitHub organization. 61 | 62 | Skills required: Node.js, Neutralinojs, Application bundling on operating systems 63 | 64 | Difficulty rating: Medium 65 | 66 | Project size: ~350h 67 | 68 | Mentors: Shalitha Suranga, Athif Shaffy, and Sainath Rao 69 | 70 | #### Suggested technical decisions 71 | 72 | - Developing a CLI plugin for the solution. 73 | - Expose a new command to generate application packages. 74 | 75 | ```bash 76 | # Installing the plugin 77 | neu plugins --add neutralinojs-builder 78 | 79 | # neu builder 80 | neu builder nsis --x64 # NSIS setup for Windows x64 81 | neu builder deb --ia32 # Debian package for GNU/Linux ia32 82 | neu builder appimage --x64 # AppImage for GNU/Linux x64 83 | neu builder deb # GNU/Linux Debian packages for all supported CPU architectures 84 | 85 | # Use configuration from neutralino.config.json 86 | neu builder 87 | 88 | # Removing the plugin 89 | neu plugins --remove neutralinojs-builder 90 | ``` 91 | - If the developer run `neu builder` without any parameters, get the targets from the config file: 92 | 93 | ```json 94 | "cli": { 95 | "builder": { 96 | "linux": { 97 | "targets": [ 98 | { 99 | "target": "deb", 100 | "arch": [ 101 | "x64", 102 | "ia32", 103 | "armhf" 104 | ] 105 | } 106 | ] 107 | }, 108 | "win": { 109 | "targets": [ 110 | { 111 | "target": "nsis", 112 | "arch": [ 113 | "x64", 114 | "ia32" 115 | ] 116 | } 117 | ] 118 | } 119 | } 120 | } 121 | ``` 122 | - Implement package targets as internal plugins (import only required modules based on targets). Try to use modules like `targets/deb.js`, `targets/nsis.js` for dynamic loading. 123 | - Keep the codebase minimal by following design patterns and principles that the official neu CLI project uses. 124 | - Use neu CLI core APIs from the plugin and avoid repetitive code between neu CLI and Neutralinojs builder projects. 125 | - Recommend users to install the builder plugin from the neu CLI if they need app installers 126 | 127 | ### Rendering a native loading animation before loading the app 128 | 129 | Neutralinojs renders the frontend web content of apps using platform-specific webview components without using a loading animation. The current implementation doesn't create any issues for small app frontends, but large frontends render a blank white screen at startup for a short period affecting the software quality and usability. The blank white screen appears for a considerable time in low-end devices and when developers load remote URLs. The only workaround for this issue is hiding and showing the app when it's ready, but it slows down the initial visible rendering time for users. This project idea suggests implementing a native loading animation for all supported platforms as a default feature to fix the startup white screen issue. 130 | 131 | Related issue: https://github.com/neutralinojs/neutralinojs/issues/814 132 | 133 | Skills required: C++, Neutralinojs, platform-specific GUI development frameworks (GTK, Windows API, and Cocoa) 134 | 135 | Difficulty rating: Medium 136 | 137 | Project size: ~350h 138 | 139 | Mentors: Shalitha Suranga, Athif Shaffy, and Sainath Rao 140 | 141 | #### Suggested UI/UX decisions 142 | 143 | - Use platform-specific spinner or infinite progress bar controls 144 | - Allow developers to use a custom GIF animation or static image 145 | - Center the loading animation within the app window 146 | - Use proper background and foreground colors based on the current system theme 147 | - Indicate the loading state in the mouse cursor by using an appropriate built-in icon 148 | 149 | #### Suggested technical decisions 150 | 151 | - Use native, built-in GUI controls in each operating system for the default loader 152 | - Let developers use a GIF from app resources and override the default loader setting 153 | - Keep the implementation only within the C++ webview library codebase fork 154 | - Use the following configuration block in `neutralino.config.json`: 155 | 156 | ```js 157 | "window": { 158 | "startupLoader": { 159 | "type": "image", // none, system (default), image 160 | "image": "/resources/images/loader.gif" 161 | } 162 | } 163 | ``` 164 | 165 | ### Extending the existing native API with essential functions 166 | 167 | Neutralinojs offers a well-structured, cross-platform native API for app developers. The current native API offers many JavaScript functions under several namespaces that most app developers can use for building general cross-platform apps. However, the current native API doesn't offer solutions for every specific development scenario -- app developers sometimes have to write native extensions or implement platform-specific command-line solutions as workarounds to implement several features that the framework itself can embed. For example, there are no built-in APIs to retrieve network details, handle file permissions, etc. This project idea suggests contributors to conduct a research for such missing framework features and implement them within the framework codebase. 168 | 169 | Related issues: [neutralinojs/neutralinojs#issues](https://github.com/neutralinojs/neutralinojs/issues?q=is%3Aissue%20state%3Aopen%20label%3AAPI%20label%3Afeature-request) 170 | 171 | Skills required: C++, JavaScript, Neutralinojs, platform-specific native APIs (POSIX and Windows APIs) 172 | 173 | Difficulty rating: Medium 174 | 175 | Project size: ~350h 176 | 177 | Mentors: Shalitha Suranga, Athif Shaffy, and Sainath Rao 178 | 179 | #### Research ideas 180 | 181 | - Evaluate existing GitHub issues and discussions 182 | - Finding missing functions by comparing Neutralinojs with other frameworks and inbuilt Node.js APIs 183 | - Search forum threads created by mentioning missing native APIs in Neutralinojs 184 | - Prepare a list of functions that can be added to the framework without heavily affecting bundle size, performance, and code complexity 185 | 186 | #### Suggested technical decisions 187 | 188 | - Implement new function names, parameters, and return values strictly adhering to the existing native API design 189 | - Search for minimal, header-only libraries if the C++ standard library doesn't offer a solution 190 | - Implement functions in a way that eliminates security vulnerabilities 191 | 192 | ### Implementing a native main menu API for window mode 193 | 194 | Neutralinojs implements the `os.setTray()` function to create a native tray menu using an icon, but the framework doesn't offer a way to create a native main menu for an app. Since there is no API function to create a main menu, app developers should alternatively register JavaScript-based keystroke listeners in macOS to activate general shortcut key combinations like Command + C and use HTML/CSS-based main menu UI implementations. This project idea suggests contributors implement the cross-platform `window.setMainMenu(menu)` function to attach a main menu for the native app window. 195 | 196 | Related issue: https://github.com/neutralinojs/neutralinojs/issues/507 197 | 198 | Skills required: C++, Neutralinojs, platform-specific GUI development frameworks (GTK, Windows API, and Cocoa) 199 | 200 | Difficulty rating: Medium 201 | 202 | Project size: ~350h 203 | 204 | Mentors: TBA 205 | 206 | #### Suggested technical decisions 207 | 208 | - Implement the `window.setMainMenu(menu)` function by maintaining consistency with the `os.setTray()` function design 209 | - Use built-in platform-specific APIs for creating native menus on each operating system 210 | - Implement the new function to support only one menu level without sub-menus (we have plans to add multi-level menu support later) as follows: 211 | 212 | ```js 213 | let menu = [ 214 | { 215 | id: "FILE", 216 | text: "File", 217 | menuItems: [ 218 | {id: "OPEN", text: "Open", shortcut: "Ctrl + O" }, 219 | {text: "-"}, 220 | {id: "EXIT", text: "Exit"} 221 | ] 222 | }, 223 | { 224 | id: "EDIT", 225 | text: "Edit", 226 | menuItems: [ 227 | {id: "CUT", text: "Cut", shortcut: "Ctrl + X" }, 228 | {id: "COPY", text: "Copy", shortcut: "Ctrl + C" }, 229 | {id: "PASTE", text: "Paste", shortcut: "Ctrl + V"} 230 | ] 231 | } 232 | ]; 233 | 234 | await Neutralino.os.setMainMenu(menu); 235 | ``` 236 | - Dispatch a new global event named `mainMenuItemClicked` similar to `trayMenuItemClicked` for binding click handlers: 237 | 238 | ```js 239 | await Neutralino.events.on('mainMenuItemClicked', (evt) => { 240 | if(evt.detail.id === "OPEN") { 241 | // Implement File -> Open 242 | } 243 | }); 244 | ``` 245 | - Keep the implementation within the C++ webview library fork 246 | 247 | ## Contributing 248 | 249 | We really appreciate your code contributions. Please read [this contribution guide](https://neutralino.js.org/docs/contributing/framework-developer-guide#contribution-guidelines) before sending a pull request. Thank you for your contributions. 250 | 251 | ## Contributors 252 | 253 | 254 | 255 | 256 | 257 | Image created with [contrib.rocks](https://contrib.rocks). 258 | 259 | ## Past programs 260 | 261 | - [GSoC 2024](https://summerofcode.withgoogle.com/programs/2024/organizations/neutralinojs) 262 | - [GSoC 2022](https://summerofcode.withgoogle.com/programs/2022/organizations/neutralinojs) 263 | 264 | --------------------------------------------------------------------------------