Skip to content

Commit 38b0740

Browse files
ivanbogaebivanbogaeb
committed
Readme
1 parent 819a183 commit 38b0740

File tree

2 files changed

+279
-38
lines changed

2 files changed

+279
-38
lines changed

‎README.md

+279-38
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,309 @@
1-
<h1 align="center">Sakura</h1>
2-
<p align="center">Sakura auto-updater, connected to github!</p>
3-
1+
<br>
2+
<p align="center"><img align="center" alt="GitHub forks" height="200" src="./sakura-logo.png"></p>
3+
<br>
4+
<h2 align="center">Bringing you an easy, simple, spring like fresh start on Electron and Node.JS updaters.</h2>
45
<hr>
5-
66
<p align="center">
7-
<a href="https://github.com/ivanbogaeb/sakupdater/network"><img alt="GitHub forks" src="https://img.shields.io/github/forks/ivanbogaeb/sakupdater"></a>
8-
<a href="https://github.com/ivanbogaeb/sakupdater/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/ivanbogaeb/sakupdater"></a>
9-
<a href="https://github.com/ivanbogaeb/sakupdater/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/ivanbogaeb/sakupdater"></a>
10-
<a href="https://github.com/ivanbogaeb/sakupdater/blob/main/LICENSE"><img alt="GitHub license" src="https://img.shields.io/github/license/ivanbogaeb/sakupdater"></a>
7+
<a href="https://github.com/ivanbogaeb/sakura/network"><img alt="GitHub forks" src="https://img.shields.io/github/forks/ivanbogaeb/sakura"></a>
8+
<a href="https://github.com/ivanbogaeb/sakura/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/ivanbogaeb/sakura"></a>
9+
<a href="https://github.com/ivanbogaeb/sakura/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/ivanbogaeb/sakura"></a>
10+
<a href="https://github.com/ivanbogaeb/sakura/blob/main/LICENSE"><img alt="GitHub license" src="https://img.shields.io/github/license/ivanbogaeb/sakura"></a>
1111
</p>
1212

1313
<br>
1414

15-
## What is sakupdater?
15+
## What is Sakura?
16+
Sakura is a minimal Electron and Node.JS auto-updater, offering developers high flexibility and modularity to work on from within their own code.
1617

17-
Sakupdater is a neat tool to create your own auto-updater system based on Github, without having to smash your head against the keyboard, saving you all the suffering.
18+
<br>
1819

1920
## Features:
21+
- File checks.
22+
- Splash screen. *(Electron only)*
23+
- Automatic updates.
24+
- Customizable alert *(Electron only)*
25+
- Latest version available.
26+
- Latest version downloader.
27+
- Private and public repository access.
2028

21-
- Get latest version available.
22-
- Get current version.
23-
- Update your stuff **(Not even finished)**
29+
<br>
30+
31+
## To-do:
32+
- [ ] Linux and iOS support.
33+
- [ ] Relaunch command on Node.JS apps.
34+
*(Currently Node.JS apps cannot execute themselves once updated)*
35+
36+
<br>
2437

2538
## Installation:
2639

2740
```console
28-
no installation yet
41+
npm install @ivanbogaeb/sakura
2942
```
3043

31-
## Usage:
44+
> Keep in mind that currently only Windows is fully supported.
45+
46+
<br>
47+
48+
## Example:
3249

3350
```javascript
34-
const Sakupdater = require('../index.js');
35-
let updater = new Sakupdater();
36-
37-
async function runAutoupdater(){
38-
39-
updater.gitUsername = 'ivanbogaeb';
40-
updater.gitRepository = 'OrbWeaver';
41-
// updater.privateToken = 'YOUR REPOSITORY PRIVATE TOKEN HERE';
42-
43-
let getLatestVersion = await updater.getLatestVersion(); // Returns latest version
44-
let downloadLatestVersion = await updater.downloadLatestVersion(); // Downloads latest version and when done returns 'true'
45-
46-
console.log(getLatestVersion);
47-
console.log(downloadLatestVersion);
48-
49-
let update = await updater.update(); // Updates your program automatically...
51+
const updated = async () => {
52+
const Sakura = require('@ivanbogaeb/sakura');
53+
try {
54+
let splashProperties = { // Create your own splash screen 👈
55+
show: true,
56+
frame: false,
57+
resizable: false,
58+
minimizable: false,
59+
maximizable: false,
60+
width: 400,
61+
height: 250,
62+
center: true,
63+
webPreferences: { // Sakura works under heavy security
64+
webSecurity: true,
65+
contextIsolation: true,
66+
preload: path.join(app.getAppPath(), './render/scripts/updater.js') // Sakura splash screen code!
67+
},
68+
icon: path.join(__dirname, './favicon.ico')
69+
};
70+
71+
let sakura = new Sakura({
72+
gitUsername: 'ivanbogaeb',
73+
gitRepository: 'sakura',
74+
privateToken: 'ghp_loOVMTQMpXz0K****************************', // If you are using a private repo!
75+
installationDirectory: path.join(__dirname, '../'), // Your main app directory
76+
hasExecutable: true, // Toggle on if you are executing EXE files
77+
executableName: 'steroid.exe',
78+
isElectron: true, // Sakura works both for Electron and Node.JS
79+
currentVersion: require('./version.json'), // Load your current version from a file
80+
});
81+
82+
// Let sakura auto-updater do the magic! Returns true when done!
83+
return await sakura.ready(splashProperties, path.join(app.getAppPath(), './render/html/updater.html'));
84+
85+
} catch (error){
86+
console.log(error);
87+
return false; // Unable to update
88+
};
89+
};
90+
91+
if (updated){
92+
// LOAD MAIN APP
5093
};
5194

52-
runAutoupdater();
5395
```
5496

55-
## Things to consider:
56-
- THIS SOFTWARE IS NOT EVEN COMPLETED, SO DON'T DOWNLOAD IT
97+
<br>
98+
99+
## Reference:
100+
101+
- [Import](#import)
102+
- [Settings](#settings)
103+
- [Functions](#functions)
104+
- [Ready()](#ready)
105+
- [Check()](#check)
106+
- [Latest()](#latest)
107+
- [Download()](#download)
108+
- [Update()](#update)
109+
- [Splash()](#splash)
110+
- [Close()](#close)
111+
- [Messenger()](#messenger)
112+
- [Splash screen](#splash-screen)
113+
114+
### Import
115+
You can simply import sakura as CommonJS module or ES, it doesn't matter!
116+
117+
- **CommonJS**:
118+
```javascript
119+
const Sakura = require('@ivanbogaeb/sakura');
120+
```
121+
- **ES Module**:
122+
```javascript
123+
import Sakura from '@ivanbogaeb/sakura';
124+
```
125+
126+
### Settings
127+
Sakura is completely customizable, in fact, you can use it's modules independently.
128+
129+
```javascript
130+
let sakura = new Sakura({
131+
gitUsername: '', // Github username
132+
gitRepository: '', // Github repository
133+
privateToken: '', // ONLY FOR PRIVATE REPOSITORIES
134+
installationDirectory: path.join(__dirname, '../'), // Your main app directory
135+
hasExecutable: true/false, // Toggle on if you require to restart your application
136+
executableName: 'APP-NAME.exe', // Name of your main EXE file
137+
isElectron: true/false, // Sakura works both for Electron and Node.JS
138+
messages: {
139+
splash: 'Loading...', // Initial message
140+
fetching: 'Checking for updates...', // While looking for updates
141+
downloading: 'Downloading new update...', // When your app is downloading
142+
updating: 'Updating...' // While it's updating
143+
},
144+
currentVersion: require('./version.json'), // Load your current version from a file, variable or string!
145+
});
146+
```
147+
148+
### Functions
149+
With this module you have the options to automate the process or take control on your own!
150+
151+
#### **`ready()`** (Recommended)
152+
Auto-updater function, it does all the process for you.
153+
```javascript
154+
let isReady = await sakura.ready(); // Returns true once the app has been updated or found it is up to date.
155+
if (isReady){
156+
// Continue normal process
157+
};
158+
```
159+
160+
#### **`check()`**
161+
Will check if you are running an update instance. If that's so, it will replace the old version with the new one and execute itself again.
162+
```javascript
163+
let isNotUpdate = await sakura.check(); // Returns true if it's not an update
164+
if (isNotUpdate){
165+
// Continue normal process
166+
};
167+
```
168+
169+
#### **`latest()`**
170+
Returns the latest version available.
171+
```javascript
172+
let latestVersion = await sakura.latest(); // Returns version string
173+
```
174+
175+
#### **`download()`**
176+
Creates an "Updates" folder inside your main application and downloads the latest version.
177+
> Must be used along [latest()](#latest). This is because Sakura has a micro internal cache where it stores the current version you are working on and also the latest, including a download URL.
178+
```javascript
179+
await sakura.latest(); // Returns version string
180+
let download = await sakura.download();
181+
if (download){
182+
// Do something after it has been downloaded
183+
};
184+
```
185+
186+
#### **`update()`**
187+
Updates your main application based on the latest version you downloaded.
188+
> Must be used along [latest()](#latest) and [download()](#download).
189+
```javascript
190+
await sakura.latest(); // Returns version string
191+
let download = await sakura.download();
192+
if (download){
193+
await sakura.update();
194+
};
195+
```
196+
197+
#### **`splash()`** (Electron only)
198+
Executes a splash screen of your choice.
199+
```javascript
200+
let splash = await sakura.splash(windowProperties, HTMLFile);
201+
```
202+
203+
#### **`close()`** (Electron only)
204+
Closes the splash screen.
205+
```javascript
206+
await sakura.close();
207+
```
208+
209+
#### **`messenger()`** (Electron only) (Not recommended to use)
210+
Talks to the splash screen by sending information throught actions.
211+
212+
**Types**:
213+
- `activate`: Window you want to send information to throught [webContents](https://www.electronjs.org/es/docs/latest/api/web-contents).
214+
> Must be used with `window` type of Payload.
215+
- `message`: Sends information to the splash screen.
216+
217+
**Payload**:
218+
- `window`: [BrowserWindow](https://www.electronjs.org/es/docs/latest/api/browser-window) you want to connect to display updates information.
219+
- `message`: This payload has four properties embed: `type`, `text`, `loader` and `percentage`.
220+
221+
**Message payload**:
222+
```javascript
223+
{
224+
type: 0, // Type 0 for messages, type 1 for downloads
225+
text: "This is an important updater message",
226+
loader: {
227+
active: false, // You can set a loader bar on and off
228+
data: 0, // Progress in kb
229+
total: 0, // Total size in kb
230+
}
231+
}
232+
```
233+
```javascript
234+
let message = await sakura.messenger({
235+
type: 'message',
236+
payload: {type: 0, text: "This is an important updater message", loader: {active: false, data: 0, total: 0}}
237+
}); // Prints on the splash screen the text!
238+
239+
let message = await sakura.messenger({
240+
type: 'message',
241+
payload: {type: 1, text: "Downloading update...", loader: {active: true, data: 900, total: 1000}}
242+
}); // Prints on the splash screen the text, activates the percentage bar to 90% completed.
243+
```
244+
245+
### Splash Screen
246+
Sakura communicates straight to the splash screen using [webContents](https://www.electronjs.org/es/docs/latest/api/web-contents). This way, you will be able to customize where you want updates information, how and which window.
247+
248+
- Create your own HTML, CSS and JavaScript files.
249+
- Inside your JavaScript file, you will have to implement this code:
250+
```javascript
251+
const { ipcRenderer } = require('electron');
252+
window.onload = async () => {
253+
ipcRenderer.on('SakuraUpdater', (event, message) => {
254+
/*
255+
Message contains:
256+
{
257+
text: "Message you sent from sakura",
258+
loader: {
259+
active: true/false,
260+
data: 0,
261+
total: 0
262+
percentage: 0 to 100
263+
}
264+
}
265+
266+
*/
267+
document.getElementById('download-label').innerText = message.text; // Sakura message updates the download label text
268+
if (message.loader.active){
269+
document.getElementById('bar-progress').style.width = message.loader.percentage + '%'; // Progress bar using CSS properties
270+
};
271+
});
272+
};
273+
```
274+
- Setup your splash screen settings:
275+
```javascript
276+
let splashScreenProperties = {
277+
show: true,
278+
frame: false,
279+
resizable: false,
280+
minimizable: false,
281+
maximizable: false,
282+
width: 400,
283+
height: 250,
284+
center: true,
285+
webPreferences: {
286+
webSecurity: true,
287+
contextIsolation: true,
288+
preload: path.join(app.getAppPath(), './render/scripts/updater.js')
289+
},
290+
icon: path.join(__dirname, '../favicon.ico')
291+
};
292+
```
293+
- Create a splash screen executing [Splash()](#splash-electron-only).
294+
295+
<br>
57296

58297
## Changelog:
59-
- 29 May 2022 - First "Release" - Version 0.6.0
60-
- **[Read more...](./changelog.md)**
298+
- 20 July 2022 - First "Release" - Version 0.9.0
299+
- **[Read more...](./CHANGELOG.md)**
61300

62-
## Credits:
301+
<br>
63302

64-
- Brought to you thanks to **ADD STUFF HERE BUT NOT TODAY**.
303+
## Credits:
65304
- Inspired by **[UAUP-JS](https://github.com/DcmanProductions/UAUP-JS)**.
66305

306+
<br>
307+
67308
## License:
68309
**[CC0 1.0 Universal](./LICENSE)**

‎sakura-logo.png

103 KB
Loading

0 commit comments

Comments
 (0)