Rename project to Nicolium
Signed-off-by: nicole mikołajczyk <git@mkljczk.pl>
This commit is contained in:
nicole mikołajczyk
@ -1,6 +1,6 @@
|
||||
# Building pl-fe
|
||||
# Building Nicolium
|
||||
|
||||
Building pl-fe requires [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/) package manager to be installed. Since Node v16.13, Node.js comes with `corepack` pre-installed, which can be used to manage package managers like `pnpm`.
|
||||
Building Nicolium requires [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/) package manager to be installed. Since Node v16.13, Node.js comes with `corepack` pre-installed, which can be used to manage package managers like `pnpm`.
|
||||
|
||||
To enable `pnpm` using `corepack`, run the following command:
|
||||
|
||||
@ -8,17 +8,17 @@ To enable `pnpm` using `corepack`, run the following command:
|
||||
corepack enable pnpm
|
||||
```
|
||||
|
||||
You can now proceed to fetching pl-fe Git repository, installing dependencies, and building the project:
|
||||
You can now proceed to fetching Nicolium Git repository, installing dependencies, and building the project:
|
||||
|
||||
```bash
|
||||
# Clone the pl-fe repository
|
||||
git clone https://codeberg.org/mkljczk/pl-fe.git
|
||||
cd pl-fe
|
||||
# Clone the Nicolium repository
|
||||
git clone https://codeberg.org/mkljczk/nicolium.git
|
||||
cd nicolium
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
# Build the pl-api dependency
|
||||
pnpm -F pl-api build
|
||||
# Build the pl-fe project
|
||||
# Build the Nicolium project
|
||||
pnpm -F pl-fe build
|
||||
```
|
||||
|
||||
@ -27,5 +27,5 @@ The built files will be located in the `packages/pl-fe/dist` directory. You can
|
||||
Following environment variables can be used to customize the instance in build process:
|
||||
|
||||
- `BACKEND_URL` - URL of the Mastodon-compatible instance to connect to. If not set, tries fetching /api/v1/instance from the origin and falls back to standalone mode.
|
||||
- `FE_SUBDIRECTORY` - The path where pl-fe is mounted to. Defaults to `/`.
|
||||
- `FE_SUBDIRECTORY` - The path where Nicolium is mounted to. Defaults to `/`.
|
||||
- `WITH_LANDING_PAGE` - Displays the landing page on the home page, when running in standalone mode.
|
||||
71
docs/contributing/nicolium.md
Normal file
71
docs/contributing/nicolium.md
Normal file
@ -0,0 +1,71 @@
|
||||
# Contributing to Nicolium
|
||||
|
||||
The page intends to provide a technical overview of the Nicolium codebase and guidelines for potential contributors.
|
||||
|
||||
## Used technologies
|
||||
|
||||
Nicolium is a single page application built using the [React](https://react.dev/) framework. It uses [TypeScript](https://www.typescriptlang.org/) as the programming language and [Vite](https://vitejs.dev/) as the build tool. Routing is handled by [TanStack Router](https://tanstack.com/router/latest). Client state management is done using [Zustand](https://zustand-demo.pmnd.rs/) and server state management using [TanStack Query](https://tanstack.com/query/latest).
|
||||
|
||||
!!! note
|
||||
Important parts of Nicolium are currently being refactored to use a different set of libraries. You can find occurrences of tools being phased out, like Redux or TailwindCSS. Larger contributions should wait until the refactor is complete.
|
||||
|
||||
Nicolium also uses `pl-api` library for interacting with the Mastodon-compatible backends. The goal of `pl-api` is to provide a unified, type-safe API for multiple backends extending Mastodon API in incompatible ways. You can find the `pl-api` source code in the `packages/pl-api` directory of the Nicolium repository.
|
||||
|
||||
## Setting up development environment
|
||||
|
||||
Setting up Nicolium requires [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/) package manager to be installed. Since Node v16.13, Node.js comes with `corepack` pre-installed, which can be used to manage package managers like `pnpm`.
|
||||
To enable `pnpm` using `corepack`, run the following command:
|
||||
|
||||
```bash
|
||||
corepack enable pnpm
|
||||
```
|
||||
|
||||
You can now proceed to fetching Nicolium Git repository, installing dependencies, and—finally—running the development server:
|
||||
|
||||
```bash
|
||||
# Clone the Nicolium repository
|
||||
git clone https://codeberg.org/mkljczk/nicolium.git
|
||||
cd nicolium
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
# Build the pl-api dependency
|
||||
pnpm -F pl-api build # Use `pnpm -F pl-api watch` if you want to develop pl-api alongside Nicolium
|
||||
# Run the Nicolium development server (by default at http://localhost:7312)
|
||||
pnpm -F pl-fe dev
|
||||
```
|
||||
|
||||
The server supports hot module reloading, so any changes you make to the source code will be reflected in the browser automatically.
|
||||
|
||||
!!! tip
|
||||
You can install the [React Developer Tools](https://react.dev/learn/react-developer-tools) browser extension to inspect components, their props and state. It might help you understand the application better and identify performance problems. It is available for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/react-devtools/), [Chrome](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en) (and compatible Chromium-based browsers) and [Edge](https://microsoftedge.microsoft.com/addons/detail/react-developer-tools/gpphkfbcpidddadnkolkpfckpihlkkil).
|
||||
|
||||
## Testing
|
||||
|
||||
Currently, tests are disabled in Nicolium. They will be reintroduced after the ongoing refactor is complete.
|
||||
|
||||
## Contributing guidelines
|
||||
|
||||
Nicolium hosts its repository on [Codeberg](https://codeberg.org/mkljczk/nicolium) and [GitHub](https://github.com/mkljczk/nicolium). While issues are only tracked on Codeberg, you can submit pull requests on both platforms. Remember to follow the [Code of Conduct](../code-of-conduct.md) when interacting with the community.
|
||||
The project uses [ESLint](https://eslint.org/) and [Stylelint](https://stylelint.io/) for code style checking, which is automatically run on every commit using [Husky](https://typicode.github.io/husky). You can run the linters manually using the following command:
|
||||
|
||||
```bash
|
||||
pnpm -F pl-fe lint
|
||||
```
|
||||
|
||||
While contributing code, try to follow the existing coding style. Common sense rules regarding contributions apply. Keep your changes focused on a single issue or feature. Do not create pull requests including larger changes you don't understand fully—whether it's from another project or some auto-generated code.
|
||||
|
||||
## Localization
|
||||
|
||||
[React Intl](https://formatjs.github.io/docs/react-intl/) is used for localizing Nicolium. All user-visible strings, unless provided by backend, should be made translatable.
|
||||
|
||||
Before committing changes adding or modifying user-visible strings, make sure to extract the messages using the following command:
|
||||
|
||||
```bash
|
||||
pnpm -F pl-fe i18n
|
||||
```
|
||||
|
||||
You can help translating Nicolium into your language on [Weblate](https://hosted.weblate.org/projects/pl-fe/).
|
||||
|
||||
<a href="https://hosted.weblate.org/engage/pl-fe/">
|
||||
<img src="https://hosted.weblate.org/widget/pl-fe/287x66-grey.png" alt="Translation status" />
|
||||
</a>
|
||||
@ -4,24 +4,23 @@
|
||||
|
||||
It uses a minimal set of dependencies, most importantly [Valibot](https://valibot.dev/) for remote data validation and guaranteeing type safety. Fetch API is used for making HTTP requests.
|
||||
|
||||
The development of `pl-api` happens inside the `pl-fe` monorepo. You can find the source code in the `packages/pl-api` directory of the `pl-fe` repository.
|
||||
The development of `pl-api` happens inside the Nicolium monorepo. You can find the source code in the `packages/pl-api` directory of the Nicolium repository.
|
||||
|
||||
## Setting up development environment
|
||||
|
||||
Setting up `pl-fe` requires [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/) package manager to be installed. Since Node v16.13, Node.js comes with `corepack` pre-installed, which can be used to manage package managers like `pnpm`.
|
||||
|
||||
Setting up Nicolium requires [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/) package manager to be installed. Since Node v16.13, Node.js comes with `corepack` pre-installed, which can be used to manage package managers like `pnpm`.
|
||||
To enable `pnpm` using `corepack`, run the following command:
|
||||
|
||||
```bash
|
||||
corepack enable pnpm
|
||||
```
|
||||
|
||||
You can now proceed to fetching pl-fe Git repository, installing dependencies, and running the development server:
|
||||
You can now proceed to fetching Nicolium Git repository, installing dependencies, and running the development server:
|
||||
|
||||
```bash
|
||||
# Clone the pl-fe repository
|
||||
git clone https://codeberg.org/mkljczk/pl-fe.git
|
||||
cd pl-fe
|
||||
# Clone the Nicolium repository
|
||||
git clone https://codeberg.org/mkljczk/nicolium.git
|
||||
cd nicolium
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
# Build the pl-api dependency
|
||||
@ -32,7 +31,7 @@ This will start a Vite development server where you can use `pl-api` client insi
|
||||
|
||||
## Contributing guidelines
|
||||
|
||||
`pl-fe` monorepo is hosted on [Codeberg](https://codeberg.org/mkljczk/pl-fe) and [GitHub](https://github.com/mkljczk/pl-fe). While issues are only tracked on Codeberg, you can submit pull requests on both platforms. Remember to follow the [Code of Conduct](../code-of-conduct.md) when interacting with the community.
|
||||
Nicolium monorepo is hosted on [Codeberg](https://codeberg.org/mkljczk/nicolium) and [GitHub](https://github.com/mkljczk/nicolium). While issues are only tracked on Codeberg, you can submit pull requests on both platforms. Remember to follow the [Code of Conduct](../code-of-conduct.md) when interacting with the community.
|
||||
|
||||
The project uses [ESLint](https://eslint.org/) for code style checking. You can run the linter using the following command:
|
||||
|
||||
|
||||
@ -1,73 +0,0 @@
|
||||
# Contributing to pl-fe
|
||||
|
||||
The page intends to provide a technical overview of the `pl-fe` codebase and guidelines for potential contributors.
|
||||
|
||||
## Used technologies
|
||||
|
||||
`pl-fe` is a single page application built using the [React](https://react.dev/) framework. It uses [TypeScript](https://www.typescriptlang.org/) as the programming language and [Vite](https://vitejs.dev/) as the build tool. Routing is handled by [TanStack Router](https://tanstack.com/router/latest). Client state management is done using [Zustand](https://zustand-demo.pmnd.rs/) and server state management using [TanStack Query](https://tanstack.com/query/latest).
|
||||
|
||||
!!! note
|
||||
Important parts of `pl-fe` are currently being refactored to use a different set of libraries. You can find occurrences of tools being phased out, like Redux or TailwindCSS. Larger contributions should wait until the refactor is complete.
|
||||
|
||||
`pl-fe` also uses `pl-api` library for interacting with the Mastodon-compatible backends. The goal of `pl-api` is to provide a unified, type-safe API for multiple backends extending Mastodon API in incompatible ways. You can find the `pl-api` source code in the `packages/pl-api` directory of the `pl-fe` repository.
|
||||
|
||||
## Setting up development environment
|
||||
|
||||
Setting up `pl-fe` requires [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/) package manager to be installed. Since Node v16.13, Node.js comes with `corepack` pre-installed, which can be used to manage package managers like `pnpm`.
|
||||
|
||||
To enable `pnpm` using `corepack`, run the following command:
|
||||
|
||||
```bash
|
||||
corepack enable pnpm
|
||||
```
|
||||
|
||||
You can now proceed to fetching pl-fe Git repository, installing dependencies, and—finally—running the development server:
|
||||
|
||||
```bash
|
||||
# Clone the pl-fe repository
|
||||
git clone https://codeberg.org/mkljczk/pl-fe.git
|
||||
cd pl-fe
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
# Build the pl-api dependency
|
||||
pnpm -F pl-api build # Use `pnpm -F pl-api watch` if you want to develop pl-api alongside pl-fe
|
||||
# Run the pl-fe development server (by default at http://localhost:7312)
|
||||
pnpm -F pl-fe dev
|
||||
```
|
||||
|
||||
The server supports hot module reloading, so any changes you make to the source code will be reflected in the browser automatically.
|
||||
|
||||
!!! tip
|
||||
You can install the [React Developer Tools](https://react.dev/learn/react-developer-tools) browser extension to inspect components, their props and state. It might help you understand the application better and identify performance problems. It is available for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/react-devtools/), [Chrome](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en) (and compatible Chromium-based browsers) and [Edge](https://microsoftedge.microsoft.com/addons/detail/react-developer-tools/gpphkfbcpidddadnkolkpfckpihlkkil).
|
||||
|
||||
## Testing
|
||||
|
||||
Currently, tests are disabled in `pl-fe`. They will be reintroduced after the ongoing refactor is complete.
|
||||
|
||||
## Contributing guidelines
|
||||
|
||||
`pl-fe` hosts its repository on [Codeberg](https://codeberg.org/mkljczk/pl-fe) and [GitHub](https://github.com/mkljczk/pl-fe). While issues are only tracked on Codeberg, you can submit pull requests on both platforms. Remember to follow the [Code of Conduct](../code-of-conduct.md) when interacting with the community.
|
||||
|
||||
The project uses [ESLint](https://eslint.org/) and [Stylelint](https://stylelint.io/) for code style checking, which is automatically run on every commit using [Husky](https://typicode.github.io/husky). You can run the linters manually using the following command:
|
||||
|
||||
```bash
|
||||
pnpm -F pl-fe lint
|
||||
```
|
||||
|
||||
While contributing code, try to follow the existing coding style. Common sense rules regarding contributions apply. Keep your changes focused on a single issue or feature. Do not create pull requests including larger changes you don't understand fully—whether it's from another project or some auto-generated code.
|
||||
|
||||
## Localization
|
||||
|
||||
[React Intl](https://formatjs.github.io/docs/react-intl/) is used for localizing `pl-fe`. All user-visible strings, unless provided by backend, should be made translatable.
|
||||
|
||||
Before committing changes adding or modifying user-visible strings, make sure to extract the messages using the following command:
|
||||
|
||||
```bash
|
||||
pnpm -F pl-fe i18n
|
||||
```
|
||||
|
||||
You can help translating `pl-fe` into your language on [Weblate](https://hosted.weblate.org/projects/pl-fe/).
|
||||
|
||||
<a href="https://hosted.weblate.org/engage/pl-fe/">
|
||||
<img src="https://hosted.weblate.org/widget/pl-fe/287x66-grey.png" alt="Translation status" />
|
||||
</a>
|
||||
@ -1,8 +1,8 @@
|
||||
# Installing pl-fe as Iceshrimp.NET frontend
|
||||
# Installing Nicolium as Iceshrimp.NET frontend
|
||||
|
||||
Iceshrimp.NET does not have built-in support for alternative frontends. However, there are ways to use `pl-fe` as the frontend for Iceshrimp.NET by rerouting specific requests using a reverse proxy like Nginx.
|
||||
Iceshrimp.NET does not have built-in support for alternative frontends. However, there are ways to use Nicolium as the frontend for Iceshrimp.NET by rerouting specific requests using a reverse proxy like Nginx.
|
||||
|
||||
While this is the only way to use some of Iceshrimp.NET-specific features with `pl-fe`, because of Iceshrimp.NET CORS configuration, remember that it doesn't have full feature parity with the default Iceshrimp.NET frontend. You might prefer using `pl-fe` [in standalone mode](./standalone.md) instead.
|
||||
While this is the only way to use some of Iceshrimp.NET-specific features with Nicolium, because of Iceshrimp.NET CORS configuration, remember that it doesn't have full feature parity with the default Iceshrimp.NET frontend. You might prefer using Nicolium [in standalone mode](./standalone.md) instead.
|
||||
|
||||
## Example Nginx configuration
|
||||
|
||||
@ -13,7 +13,7 @@ map $http_upgrade $connection_upgrade {
|
||||
}
|
||||
|
||||
map "$http_accept,$http_content_type" $maybe_activitypub {
|
||||
default @plfe;
|
||||
default @nicolium;
|
||||
|
||||
"~application/json" @shrimp;
|
||||
"~application/activity\+json" @shrimp;
|
||||
@ -37,7 +37,7 @@ server {
|
||||
try_files /dev/null $maybe_activitypub;
|
||||
}
|
||||
|
||||
location @plfe {
|
||||
location @nicolium {
|
||||
try_files /index.html /dev/null;
|
||||
}
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Installing pl-fe as Mitra frontend
|
||||
# Installing Nicolium as Mitra frontend
|
||||
|
||||
Installing `pl-fe` as a frontend for Mitra is no different from installing the default Mitra Web frontend. Just extract the `pl-fe` files into the directory specified in `config.yaml` under `web_client_dir`, by default `/usr/share/mitra/www`.
|
||||
Installing Nicolium as a frontend for Mitra is no different from installing the default Mitra Web frontend. Just extract the Nicolium files into the directory specified in `config.yaml` under `web_client_dir`, by default `/usr/share/mitra/www`.
|
||||
|
||||
```bash
|
||||
curl -O https://pl.mkljczk.pl/pl-fe.zip
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
# Installing pl-fe as Pleroma/Akkoma frontend
|
||||
# Installing Nicolium as Pleroma/Akkoma frontend
|
||||
|
||||
## Installation in instance static directory
|
||||
|
||||
The most straightforward way to install `pl-fe` as a frontend for Pleroma or Akkoma is to simply download it and place its files in the `/instance/static` directory of your Pleroma/Akkoma installation (usually `/opt/pleroma/instance/static` or `/opt/akkoma/instance/static`, accordingly).
|
||||
The most straightforward way to install Nicolium as a frontend for Pleroma or Akkoma is to simply download it and place its files in the `/instance/static` directory of your Pleroma/Akkoma installation (usually `/opt/pleroma/instance/static` or `/opt/akkoma/instance/static`, accordingly).
|
||||
|
||||
```bash
|
||||
curl -O https://pl.mkljczk.pl/pl-fe.zip
|
||||
@ -12,9 +12,9 @@ rm pl-fe.zip
|
||||
|
||||
## Installation via Pleroma/Akkoma frontend management
|
||||
|
||||
It is also possible to use the Pleroma frontend management tool. You can find more information about it in the [Pleroma documentation](https://docs.pleroma.social/backend/administration/frontends-management/). On Pleroma, you can use either the PleromaFE built-in admin dashboard or the older AdminFE to install `pl-fe` and set it as the server frontend. You don't have to provide any URL. It's right there in Pleroma.
|
||||
It is also possible to use the Pleroma/Akkoma frontend management tool. You can find more information about it in the [Pleroma documentation](https://docs.pleroma.social/backend/administration/frontends-management/). You can use either the PleromaFE built-in admin dashboard or the older AdminFE to install Nicolium and set it as the server frontend. You don't have to provide any URL. It's right there in Pleroma/Akkoma.
|
||||
|
||||
On Akkoma, however, there is no `pl-fe` in the default available frontends list ([yet?](https://akkoma.dev/AkkomaGang/akkoma/pulls/945)). You can still install it, but you need to explicitly provide the URL to `pl-fe`. To install it from CLI, use:
|
||||
To install it from CLI, use:
|
||||
|
||||
### OTP
|
||||
```bash
|
||||
@ -27,7 +27,7 @@ On Akkoma, however, there is no `pl-fe` in the default available frontends list
|
||||
mix pleroma.frontend install pl-fe --ref develop --build-url https://pl.mkljczk.pl/pl-fe.zip --build-dir .
|
||||
```
|
||||
|
||||
It is now possible to set `pl-fe` as the primary frontend in the configuration file or via AdminFE:
|
||||
It is now possible to set Nicolium as the primary frontend in the configuration file or via AdminFE:
|
||||
```elixir
|
||||
config :pleroma, :frontends,
|
||||
primary: %{
|
||||
@ -37,4 +37,4 @@ config :pleroma, :frontends,
|
||||
...
|
||||
```
|
||||
|
||||
On Akkoma, it is also possible for individual users to select their preferred frontend to `pl-fe` by visiting `/akkoma/frontend` page on their Akkoma instance.
|
||||
On Akkoma, it is also possible for individual users to select their preferred frontend to Nicolium by visiting `/akkoma/frontend` page on their Akkoma instance.
|
||||
@ -1,16 +1,16 @@
|
||||
# Standalone pl-fe installation
|
||||
# Standalone Nicolium installation
|
||||
|
||||
To install `pl-fe` in standalone mode, allowing to sign in to any instance implementing Mastodon client API, you only need a static web server to serve the files. As usual on single page applications with client-side routing, the server must be configured to fallback to `index.html` for non-matching routes.
|
||||
To install Nicolium in standalone mode, allowing to sign in to any instance implementing Mastodon client API, you only need a static web server to serve the files. As usual on single page applications with client-side routing, the server must be configured to fallback to `index.html` for non-matching routes.
|
||||
|
||||
## Example Caddy configuration
|
||||
|
||||
```caddy
|
||||
pl-fe.example.com {
|
||||
root * /var/www/pl-fe
|
||||
nicolium.example.com {
|
||||
root * /var/www/nicolium
|
||||
encode
|
||||
try_files {path} /index.html
|
||||
file_server
|
||||
}
|
||||
```
|
||||
|
||||
This assumes you're serving `pl-fe` under the pl-fe.example.com domain and the `pl-fe` files are located in `/var/www/pl-fe`. You can download `pl-fe` from `https://pl.mkljczk.pl/pl-fe.zip` or [build it from source](../building/pl-fe.md).
|
||||
This assumes you're serving Nicolium under the nicolium.example.com domain and the Nicolium files are located in `/var/www/nicolium`. You can download Nicolium from `https://pl.mkljczk.pl/pl-fe.zip` or [build it from source](../building/nicolium.md).
|
||||
Reference in New Issue
Block a user