Supporting clubs and non-profits with great software
We recently moved to a monorepo to make it easier for new contributors to make changes without having to work in different repositories and creating multiple pull requests. Now you can bundle all your changes in one pull request.
For everything frontend related, you can take a look at the readme in the frontend folder. We have two SPA, written with Vue + TypeScript. The frontend is build on a custom (open-source) framework 'vue-app-navigation' that makes handing responsive and app-like views/navigation/animations easy. You'll see that it is easy to learn and understand.
Documentation and code is located in the backend folder.
We have some packages that are shared between the frontend and backend. The most important one is structures. This package contains all the data structures (communication in the API, stored in the backend, in an encrytped blob or in localstorage) and how they should be encoded and decoded. The data structures are versioned: when an old client communicates with an updated backend, everything will work as usual. Make sure you keep everything backwards compatible, read the documantation in @simonbackx/simple-encoding. If you need to add some new data, you'll probably need to make some changes in this package.
Do you want to contribute? GREAT! :D You can build features that you need for your own club or you can help the project.
This is what you need to know:
- Try to keep all communication in English, even when you know everyone is speaking the same language. It makes it easier for others to find answers to some questions later on and to join a conversation. We know the software is currently in Dutch only, but that will change in the future ;)
- We recommend you to create an issue before starting to build something (unless it is a bugfix or a small improvement, then you can open up a PR right away). Big features should be discussed first.
- Look at the issues if you want to help build something, or open an issue if you want to help but don't know where to start. Tip: you can look at our feedback system (https://stamhoofd.nolt.io to find inspiration).
- Create a pull request, make a draft if you feel some discussion is needed or if you want to show your WIP
To run everything locally, we need to glue all the packages together and build them. We only publish packages to the NPM registry during a release.
- We use
yarn. Do not usenpm. That will break things. Useyarn policies set-version 1.19.0to set the version of yarn to the one used in the project (and the server). Replace 1.19.0 with the version in package.json > engines > yarn. We use version version 1.19.0 of yarn because of a bug in workspaces after that version (yarnpkg/yarn#7807). - When switching branches, cloning the repo or when pulling changes, run
yarn install && yarn buildfirst in the project root. We use yarn workspaces to glue all packages together in the monorepo. We don't publish individual packages (not anymore, we used to do that). - Use
yarn buildin the project directory to build all shared dependencies inside the project. This will make sure eslint works correctly. - Install all needed vscode extensions: vetur & eslint. Please use VSCode because that makes sure all the developer tools are the same (e.g. eslint).
- Make sure you create
/backend/.envbased on/backend/.env.template - Run tests before creating a pull request.
Use these commands in /backend
yarn build- Build the backend into the /dist folder, using TypeScript cache if possible.
yarn build:full- Build the backend into the /dist folder, clearing cache before building
yarn start- Run the backend server locally. This will use the
/backend/.envfile for configuration. You can use .env.template to create your own .env file. yarn migrations- Run all the migrations. If you don't have the tables in your database, this will also create all the tables. You'll need to create the database yourself (choose your connection details and name in .env)
yarn test- Run the tests on a separate test database. You'll need to setup .env.test (same as .env, but please modify it first and make sure
NODE_ENV=testis in it)
You can use the following commands in both /frontend/app/registration and /frontend/app/dashboard (the current frontend apps)
yarn build- Build the whole app into /dist, without optimizations (for development)
yarn build:production- Build the whole app into /dist, with optimizations
yarn serve- Serve the frontend locally with HMR (use this for development in combination with
yarn startin the backend)
All shared dependencies are located in /shared. These packages are used by the backend and the frontend. If you make changes here, you must rebuild the package with yarn build. You can rebuild them all at once by running the same command in the project root.
Feedback and ideas: Feedback (use this for feature suggestions instead of issues)
More info on our website: Stamhoofd
Translations are still WIP, not all strings are ported to the translations files yet. Feel free to contribute here!
Translations are stored inside the package shared/locales. They need to get build (cd shared/locales && yarn build), because we use one single .json file to store each locale (this makes it easier to use developer and translation tools). Before we use those in the frontend, we need to filter out unused translations to save some bandwidth, that is what happens in the build step. Translations are divided in 4 namespaces: shared, dashboard, registration and webshop. The shared namespace is always loaded. For the dashboard frontend, only the dashboard namespace is loaded etc. After the build step, we have 4 JSON files (one for each namespace) for each locale. The frontend and backend knows which file to load.
The possible language / country combinations are not restricted. E.g. en-NL is still a valid locale, for users from the Netherlands who want to use the English version.
Translations are resolved in the following order: en-NL > en. So translations from a specific language + country combination are used before the translation for a given language. Try to define most translations only in the language.json file, only country specific translations should be placed in the full locale files.
Stamhoofd is open-source software, licensed under the GNU Affero General Public License Version 3 (AGPLv3). View license.