Skip to content

Commit 2a5969e

Browse files
committed
README updates
1 parent 575201d commit 2a5969e

File tree

1 file changed

+52
-147
lines changed

1 file changed

+52
-147
lines changed

README.md

Lines changed: 52 additions & 147 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,15 @@
66
[![GitHub Repo stars](https://img.shields.io/github/stars/birdofpreyru/react-native-static-server?style=social)](https://github.com/birdofpreyru/react-native-static-server)
77
[![Dr. Pogodin Studio](https://raw.githubusercontent.com/birdofpreyru/react-native-static-server/master/.README/logo-dr-pogodin-studio.svg)](https://dr.pogodin.studio/docs/react-native-static-server)
88

9+
<!-- Misc links -->
10+
[GCDWebServer]: https://github.com/swisspol/GCDWebServer
11+
[NanoHttpd]: https://github.com/NanoHttpd/nanohttpd
12+
[Lighttpd]: https://www.lighttpd.net
13+
[New Architecture]: https://reactnative.dev/docs/the-new-architecture/landing-page
14+
[Old Architecture]: https://reactnative.dev/docs/native-modules-intro
15+
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
16+
[React Native]: https://reactnative.dev
17+
918
Embedded HTTP server for [React Native] applications for Android, iOS, Mac (Catalyst),
1019
and Windows platforms. Powered by [Lighttpd] server, supports both [new][New Architecture]
1120
and [old][Old Architecture] RN architectures.
@@ -58,20 +67,56 @@ and [old][Old Architecture] RN architectures.
5867
- [Enabling Rewrite module]
5968
- [Enabling WebDAV module]
6069
- [API Reference](#api-reference)
61-
- [Project History and Roadmap](#project-history-and-roadmap)
62-
- [Notable Versions of the Library]
63-
- [Roadmap]
64-
- [Documentation for Older Library Versions (v0.6, v0.5)][OLD-README.md]
65-
- [Migration from Older Versions (v0.6, v0.5) to v0.7](#migration-from-older-versions-v06-v05-to-v07)
70+
- [Server] &mdash; Represents a server instance.
71+
- [constructor()] &mdash; Creates a new [Server] instance.
72+
- [.addStateListener()] &mdash; Adds state listener to the server instance.
73+
- [.removeAllStateListeners()] &mdash; Removes all state listeners from this
74+
server instance.
75+
- [.removeStateListener()] &mdash; Removes specified state listener from this
76+
server instance.
77+
- [.start()] &mdash; Launches the server.
78+
- [.stop()] &mdash; Stops the server.
79+
- [.errorLog] &mdash; Holds `errorLog` configuration.
80+
- [.fileDir] &mdash; Holds absolute path to static assets on target device.
81+
- [.hostname] &mdash; Holds the hostname used by server.
82+
- [.id] &mdash; Hold unique ID of the server instance.
83+
- [.nonLocal] &mdash; Holds `nonLocal` value provided to [constructor()].
84+
- [.origin] &mdash; Holds server origin.
85+
- [.port] &mdash; Holds the port used by server.
86+
- [.state] &mdash; Holds the current server state.
87+
- [.stopInBackground] &mdash; Holds `stopInBackground` value provided to
88+
[constructor()].
89+
- [extractBundledAssets()] &mdash; Extracts bundled assets into a regular folder
90+
(Android-specific).
91+
- [getActiveServer()] &mdash; Gets currently active, starting, or stopping
92+
server instance, if any.
93+
- [resolveAssetsPath()] &mdash; Resolves relative paths for bundled assets.
94+
- [ERROR_LOG_FILE] &mdash; Location of the error log file.
95+
- [STATES] &mdash; Enumerates possible states of [Server] instance.
96+
- [UPLOADS_DIR] &mdash; Location for uploads.
97+
- [WORK_DIR] &mdash; Location of the working files.
98+
- [ErrorLogOptions] &mdash; Options for error logging.
6699

67100
## Getting Started
68101
[Getting Started]: #getting-started
69102

70103
[CMake]: https://cmake.org
71104
[Homebrew]: https://brew.sh
72105

73-
**Note:** _In addition to these instructions, have a look at
74-
[the example project][example app] included into the library repository._
106+
- **Note:**
107+
108+
- This library's repository includes [Example App][example app].
109+
Have a look, try to build it, in addition to following the instructions
110+
below.
111+
112+
- The following host / build platforms are not currently supported officially,
113+
and they won't be unless the support is provided or sponsored by somebody:
114+
- Building for Android target on Windows host
115+
([open issues](https://github.com/birdofpreyru/react-native-static-server/issues?q=is%3Aissue+is%3Aopen+label%3A%22Windows+-%3E+Android%22)).
116+
Prefer building for Android on macOS or Ubuntu host.
117+
- [Expo] ([open issues](https://github.com/birdofpreyru/react-native-static-server/issues?q=is%3Aissue+is%3Aopen+label%3AExpo)).
118+
- [tvOS](https://developer.apple.com/tvos) ([open issues](https://github.com/birdofpreyru/react-native-static-server/issues?q=is%3Aissue+is%3Aopen+label%3AtvOS)).
119+
75120

76121
- [CMake] is required on the build host.
77122

@@ -441,36 +486,6 @@ routes when you create [Server] instance, using `extraConfig` option.
441486
```
442487
443488
## API Reference
444-
- [Server] &mdash; Represents a server instance.
445-
- [constructor()] &mdash; Creates a new [Server] instance.
446-
- [.addStateListener()] &mdash; Adds state listener to the server instance.
447-
- [.removeAllStateListeners()] &mdash; Removes all state listeners from this
448-
server instance.
449-
- [.removeStateListener()] &mdash; Removes specified state listener from this
450-
server instance.
451-
- [.start()] &mdash; Launches the server.
452-
- [.stop()] &mdash; Stops the server.
453-
- [.errorLog] &mdash; Holds `errorLog` configuration.
454-
- [.fileDir] &mdash; Holds absolute path to static assets on target device.
455-
- [.hostname] &mdash; Holds the hostname used by server.
456-
- [.id] &mdash; Hold unique ID of the server instance.
457-
- [.nonLocal] &mdash; Holds `nonLocal` value provided to [constructor()].
458-
- [.origin] &mdash; Holds server origin.
459-
- [.port] &mdash; Holds the port used by server.
460-
- [.state] &mdash; Holds the current server state.
461-
- [.stopInBackground] &mdash; Holds `stopInBackground` value provided to
462-
[constructor()].
463-
- [extractBundledAssets()] &mdash; Extracts bundled assets into a regular folder
464-
(Android-specific).
465-
- [getActiveServer()] &mdash; Gets currently active, starting, or stopping
466-
server instance, if any.
467-
- [resolveAssetsPath()] &mdash; Resolves relative paths for bundled assets.
468-
- [ERROR_LOG_FILE] &mdash; Location of the error log file.
469-
- [STATES] &mdash; Enumerates possible states of [Server] instance.
470-
- [UPLOADS_DIR] &mdash; Location for uploads.
471-
- [WORK_DIR] &mdash; Location of the working files.
472-
- [ErrorLogOptions] &mdash; Options for error logging.
473-
474489
### Server
475490
[Server]: #server
476491
```js
@@ -880,113 +895,3 @@ the similarly named
880895
881896
Without any flag set the server instance will still output very basic state
882897
and error messages into the log file.
883-
884-
## Project History and Roadmap
885-
886-
[GCDWebServer]: https://github.com/swisspol/GCDWebServer
887-
[NanoHttpd]: https://github.com/NanoHttpd/nanohttpd
888-
[Lighttpd]: https://www.lighttpd.net
889-
[New Architecture]: https://reactnative.dev/docs/the-new-architecture/landing-page
890-
[Old Architecture]: https://reactnative.dev/docs/native-modules-intro
891-
[React Native]: https://reactnative.dev
892-
893-
This project started as a fork of the original
894-
[`react-native-static-server`](https://www.npmjs.com/package/react-native-static-server)
895-
library, abandoned by its creators.
896-
It is published to NPM as
897-
[@dr.pogodin/react-native-static-server](https://www.npmjs.com/package/@dr.pogodin/react-native-static-server),
898-
and it aims to provide a well-maintained embed HTTP server for React Native (RN)
899-
applications.
900-
901-
### Roadmap
902-
[Roadmap]: #roadmap
903-
904-
**NOTE:** _With an appropriate financial contribution you can influence
905-
the roadmap&nbsp;&mdash; the aims, priorities, and timelines for this
906-
library&nbsp;&mdash; everything can be adjusted for the needs of a paying
907-
customer._
908-
909-
These are future development aims, ordered by their current priority (from
910-
the top priority, to the least priority):
911-
912-
- Support of custom configuration of HTTP server, and inclusion of
913-
additional [Lighttpd] plugins (only three plugins for serving static
914-
assets are included now by default on all platforms).
915-
- Support of [Expo].
916-
- Better documentation (migration of the documentation
917-
to a [Docusaurus](https://docusaurus.io) website.
918-
919-
### Notable Versions of the Library
920-
[Notable Versions of the Library]: #notable-versions-of-the-library
921-
[Releases Page on GitHub]: https://github.com/birdofpreyru/react-native-static-server/releases
922-
923-
- See [Releases Page on GitHub] for details on latest library versions,
924-
which did not deserve a special mention here.
925-
926-
- **v0.7.0** &mdash; The new version of the library. Reworked API,
927-
powered by [Lighttpd] v1.4.69 and latest [React Native] v0.71.2
928-
on both Android and iOS, supports both [new][New Architecture]
929-
and [old][Old Architecture] RN Architectures.
930-
931-
- **v0.6.0-alpha.8** &mdash; The aim for **v0.6** release was
932-
to refactor the library to support React Native's [New Architecture],
933-
while keeping backward compatibility with RN's [Old Architecture],
934-
and the original library API. The aim was mostly achieved as of
935-
v0.6.0-alpha.8, but as development focus shifted into v0.7 development,
936-
the v0.6 was effectively abandoned.
937-
938-
As of the latest alpha v0.6 version, the status was:
939-
- The code refactoring was completed.
940-
- **Android**: relied on [NanoHttpd], tested with React Native v0.70.0 for
941-
both RN's [old][Old Architecture] and [new][New Architecture] architectures.
942-
- **iOS**: relied on [GCDWebServer], tested with React Native v0.70.0 for
943-
RN's [Old Architecture]. \
944-
**NOT TESTED** with RN's [New Architecture], it likely required minor fixes
945-
to support it.
946-
947-
- **v0.5.5** &mdash; The latest version of the original library, patched
948-
to work with React Native v0.67&ndash;0.68, and with all dependencies
949-
updated (as of May 17, 2022). Relies on [NanoHttpd] on Android,
950-
and [GCDWebServer] on iOS; only supports RN's [Old Architecture],
951-
and was not tested with RN v0.69+.
952-
953-
## Documentation for Older Library Versions (v0.6, v0.5)
954-
See [OLD-README.md]
955-
956-
## Migration from Older Versions (v0.6, v0.5) to v0.7
957-
958-
- On **Android** it now requires `minSdkVersion` to be set in equal 28 or larger
959-
(in `build.gradle` file). Also, now it is not supported to start more than one
960-
server instance a time (previously started server instance, if any, must be
961-
stopped before starting another one).
962-
963-
- [Server]'s [constructor()] signature was changed, as well as default behavior:
964-
- [constructor()] now accepts a single required argument: an object holding
965-
all available server options:
966-
- `fileDir` option replaces old `root` argument, and now it MUST BE
967-
a non-empty string (to prevent any mistakes due to wrong assumptions
968-
what folder is served by default).
969-
- `nonLocal` option replaces the old `localOnly` option, with the opposite
970-
meaning and default behavior. Now, by default the server is started on
971-
"`127.0.0.1`" (the loopback address) and is only accessible from within the app. Setting `nonLocal`
972-
flag will start it on an automatically assigned IP, accessible from outside
973-
the app as well. This is the opposite to behavior in previous versions, and
974-
it feels more secure (prevents exposing server outside the app due to
975-
overlooking the default behavior).
976-
- `stopInBackground` option replaces the old `keepAlive` option, with
977-
the opposite meaning and behavior. Now, by default the server does not
978-
do anything special when the app goes into background / returns to foreground.
979-
Setting `stopInBackground` **true** will cause automatic stop of the server
980-
each time the app enters background, with subsequent automatic server restart
981-
when the app returns to foreground. This is opposite to behavior in previous
982-
versions, and the rationale is: it is easy to handle the server without
983-
stopping in background (in this case there is no need to watch server state
984-
and synchronize possible requests with current server state), thus new
985-
default behavior allows for easier server usage, while the opt-in stopping
986-
of server in background allows more advanced usage scenario.
987-
988-
- The new server implementation relies on app's temporary data folder to store
989-
internal files (all within its [WORK_DIR]), don't mess with it if you do
990-
anything special with the temporary folder.
991-
992-
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

0 commit comments

Comments
 (0)