How to deploy Angular on Saplo (enterprise SPA)

Angular is the most complete of the popular frontend frameworks - it imposes its own project structure, TypeScript typing, and modules, which works well for large enterprise applications maintained by an entire team. Like React or Vue, Angular itself is not a hosting platform - a built project consists of static HTML, CSS, and JS files that require a server with a correct route fallback for Angular Router in history mode. On Saplo, you deploy Angular exactly like any other application from the catalog: the engine scaffolds the project, builds it with Angular CLI, detects the actual directory with the resulting index.html, and exposes it under nginx along with the route fallback.

Who is Angular on Saplo for?

Before you start the installation, check if it's the right choice for your project:

• you are building a large internal system or a panel for multiple roles - Angular's module structure and strict typing make it easier to maintain code when several people are working on the project,
• the team already knows Angular - Saplo doesn't impose any additional layer, you get a standard project generated by Angular CLI,
• the frontend is to connect to its own API - you set up SPA next to the backend (Django, Node, Docker) on the same Box or separately,
• single-page application with Angular Router in history mode - fallback of all routes to index.html is configured automatically, you don't need to add anything in nginx,
• you want deployments with git push instead of manual file transfer via FTP - you connect the repository once, each push to the production branch builds and deploys a new version automatically.

If the project is smaller and you don't need the full Angular module structure, check the app catalog for lighter React or Vue stacks.

Requirements

To run Angular on Saplo, you need:

• A Box at least on the S plan - a built SPA is a handful of static files, but the Angular CLI build process itself is heavier than in React or Vue. That's why the recipe's manifest requires a minimum of 512 MB of free RAM for the build and 3 GB of disk space.
• A domain or subdomain *.saploapp.pl included in the price of every plan.
• A Git repository if you want automatic deployments (optional to start, you can also upload the application as an archive .zip through the panel).

Step-by-step installation

1. In the Saplo panel, go to the App catalog and select Angular ("Applications" category).
2. Select your Box and application name - this will create the default subdomain <name>.saploapp.pl.
3. Select the Node.js version for the build (18, 20 or 22, default 20) and confirm the installation.
4. The engine scaffolds the Angular boilerplate using Angular CLI (equivalent of ng new --defaults --ssr=false), installs dependencies, and builds the project for production (ng build --configuration=production).
5. After the build, the engine automatically detects whether the output file index.html is located in dist/<project>/ (Angular older than 17) or in dist/<project>/browser/ (Angular 17 and newer, where the dist directory is prepared for SSR), and copies the correct directory level to the application served by nginx.
6. Once the installation is complete, the domain from step 2 will show the basic Angular boilerplate - from this point on, you deploy your own code to it.

Deploying Your Own Code via Git

1. In the application details, find the Git / CI-CD section and click "Connect GitHub", confirm the installation of the "Saplo Deploy" app, and select your Angular project repository.
2. The saplo.yaml file must be in the root directory of the repository.
3. Commit and push the saplo.yaml file to the production branch (default is main).
4. Each subsequent git push to this branch builds the project and replaces the resulting files on the Box. You can see the status in the Deployments tab.
5. If the build fails, the previous working version remains in place - Saplo will not replace it with a broken one.

Example of a minimal saplo.yaml file for Angular:

name: my-project
stack: angular
build:
  install: npm ci
  command: npm run build
  output: dist/my-project/browser

If you don't set the build.output field, the engine will still detect the correct directory with index.html automatically, but explicit settings speed up the build and eliminate errors in projects with non-standard names.

Angular on Saplo vs. Alternatives

FAQ

Does Angular Router in history mode work without additional configuration? Yes, the fallback of all paths to index.html is active immediately after installation, so refreshing any subpage does not result in a 404 error.

Angular 17 changed the dist directory structure - is this a problem on Saplo? No, after the build, the engine automatically checks whether index.html is located in dist/<project>/ or dist/<project>/browser/, and copies the correct directory level without your involvement.

Can I have multiple Angular applications on one Box? Yes, the App catalog allows you to set up many modules side-by-side, each with its own subdomain or domain.

Will I get SSL and my own domain? Yes, the SSL certificate is automatic, and you get a domain or subdomain *.saploapp.pl included in the price of every plan.

How do I change the build output directory if my project has a custom name? Set the build.output field in saplo.yaml to the correct path, for example dist/project-name/browser.

You can set up Angular on Saplo from scratch to a working domain in minutes, and the engine automatically detects changes in the dist directory structure between Angular versions. If your project is smaller than a typical enterprise application, check out the lighter React or Vue stacks in the same catalog.