diff --git a/docs/building.md b/docs/building.md index 087e03c88..c8f8cfc80 100644 --- a/docs/building.md +++ b/docs/building.md @@ -17,11 +17,9 @@ cd pl-fe # Install dependencies pnpm install # Build the pl-api dependency -cd packages/pl-api -pnpm build -cd ../pl-fe +pnpm -F pl-api build # Build the pl-fe project -pnpm build +pnpm -F pl-fe build ``` The built files will be located in the `packages/pl-fe/dist` directory. You can [serve them using a static web server](./installing/standalone.md). \ No newline at end of file diff --git a/docs/code-of-conduct.md b/docs/code-of-conduct.md new file mode 100644 index 000000000..601bf81f8 --- /dev/null +++ b/docs/code-of-conduct.md @@ -0,0 +1,6 @@ +# Code of Conduct + +{% + include "../CODE_OF_CONDUCT.md" + start='\n\n' +%} diff --git a/docs/contributing/pl-api.md b/docs/contributing/pl-api.md new file mode 100644 index 000000000..8cf78e5e3 --- /dev/null +++ b/docs/contributing/pl-api.md @@ -0,0 +1,43 @@ +# Contributing to pl-api + +`pl-api` is a TypeScript library for interacting with Mastodon-compatible backends, focused on supporting multiple projects extending the official Mastodon API in incompatible ways. The goal of `pl-api` is to provide a unified, type-safe API for these backends. + +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. + +## 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 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 dev +``` + +This will start a Vite development server where you can use `pl-api` client inside browser devtools console for testing purposes. It is available globally as `window.PlApiClient`. + +## 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. + +The project uses [ESLint](https://eslint.org/) for code style checking. You can run the linter using the following command: + +```bash +pnpm -F pl-api 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. \ No newline at end of file diff --git a/docs/contributing/pl-fe.md b/docs/contributing/pl-fe.md new file mode 100644 index 000000000..512f463ef --- /dev/null +++ b/docs/contributing/pl-fe.md @@ -0,0 +1,73 @@ +# 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/). + + +Translation status + \ No newline at end of file diff --git a/packages/pl-api/index.html b/packages/pl-api/index.html index 99b1f02fa..4c7eed0bf 100644 --- a/packages/pl-api/index.html +++ b/packages/pl-api/index.html @@ -10,7 +10,7 @@ diff --git a/packages/pl-api/lib/entities/media-attachment.ts b/packages/pl-api/lib/entities/media-attachment.ts index 985090939..187909889 100644 --- a/packages/pl-api/lib/entities/media-attachment.ts +++ b/packages/pl-api/lib/entities/media-attachment.ts @@ -8,7 +8,7 @@ import { mimeSchema } from './utils'; */ const blurhashSchema = v.pipe(v.string(), v.check( (value) => isBlurhashValid(value).result, - 'invalid blurhash', // .errorReason + 'invalid blurhash', )); const baseAttachmentSchema = v.object({ diff --git a/packages/pl-api/package.json b/packages/pl-api/package.json index 72f7503cf..c2e6d8414 100644 --- a/packages/pl-api/package.json +++ b/packages/pl-api/package.json @@ -12,7 +12,8 @@ }, "scripts": { "dev": "vite", - "build": "tsc --p ./tsconfig-build.json && vite build", + "build": "vite build", + "watch": "vite build --watch", "preview": "vite preview", "lint": "npx eslint --ext .js,.jsx,.cjs,.mjs,.ts,.tsx . --cache" }, diff --git a/packages/pl-api/tsconfig-build.json b/packages/pl-api/tsconfig-build.json deleted file mode 100644 index 160480b19..000000000 --- a/packages/pl-api/tsconfig-build.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "extends": "./tsconfig.json", - "include": ["lib"] - } \ No newline at end of file diff --git a/packages/pl-api/tsconfig.json b/packages/pl-api/tsconfig.json index dc67c03f5..46095c7f4 100644 --- a/packages/pl-api/tsconfig.json +++ b/packages/pl-api/tsconfig.json @@ -20,5 +20,5 @@ "noUnusedParameters": true, "noFallthroughCasesInSwitch": true }, - "include": ["src", "lib"] + "include": ["lib"] } diff --git a/packages/pl-api/vite.config.ts b/packages/pl-api/vite.config.ts index 0928cfc7a..d14779539 100644 --- a/packages/pl-api/vite.config.ts +++ b/packages/pl-api/vite.config.ts @@ -21,4 +21,7 @@ export default defineConfig({ external: Object.keys(pkg.dependencies), }, }, + server: { + port: Number(process.env.PORT ?? 7313), + }, }); diff --git a/packages/pl-fe/vite.config.ts b/packages/pl-fe/vite.config.ts index 5d6ff8a8d..96ae243c8 100644 --- a/packages/pl-fe/vite.config.ts +++ b/packages/pl-fe/vite.config.ts @@ -29,7 +29,7 @@ const config = defineConfig(({ command }) => ({ }, assetsInclude: ['**/*.oga'], server: { - port: Number(process.env.PORT ?? 3036), + port: Number(process.env.PORT ?? 7312), hmr: process.env.HMR_DISABLED === 'true' ? false : undefined, }, plugins: [