diff --git a/blog-posts/en/2026-04-02-angular-aspnet-core-getting-started-guide/angular-aspnet-core-getting-started-guide.md b/blog-posts/en/2026-04-02-angular-aspnet-core-getting-started-guide/angular-aspnet-core-getting-started-guide.md new file mode 100644 index 00000000..9bfb90cc --- /dev/null +++ b/blog-posts/en/2026-04-02-angular-aspnet-core-getting-started-guide/angular-aspnet-core-getting-started-guide.md @@ -0,0 +1,383 @@ +# Angular + ASP.NET Core: Enterprise Project Getting Started Guide (2026) + +If you are building an enterprise web application in 2026, the combination of **Angular** and **ASP.NET Core** is one of the strongest choices you can make. Angular gives you TypeScript safety, a powerful component architecture, and a mature ecosystem. ASP.NET Core gives you a high-performance, cross-platform backend with first-class dependency injection and a rich middleware pipeline. + +In this post, we will walk through **three different ways** to start an Angular + ASP.NET Core project — from a fully manual setup to a one-click enterprise starter. By the end, you will have a clear understanding of which approach fits your project best. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Approach 1 — Manual Setup](#approach-1--manual-setup) + - [Step 1: Create the Angular App](#step-1-create-the-angular-app) + - [Step 2: Create the ASP.NET Core Web API](#step-2-create-the-aspnet-core-web-api) + - [Step 3: Configure CORS](#step-3-configure-cors) + - [Step 4: Set Up the Angular Proxy](#step-4-set-up-the-angular-proxy) + - [Step 5: Make the First API Call](#step-5-make-the-first-api-call) +- [Approach 2 — Visual Studio Template](#approach-2--visual-studio-template) +- [Approach 3 — ASP.NET Zero](#approach-3--aspnet-zero) +- [Comparison](#comparison) +- [Common Issues and Solutions](#common-issues-and-solutions) +- [Next Steps](#next-steps) + +## Prerequisites + +Before we start, make sure you have the following tools installed: + +- **Node.js** 24.x or later — [download here](https://nodejs.org/) +- **Angular CLI** 21.x — install with `npm install -g @angular/cli` +- **.NET 10 SDK** — [download here](https://dotnet.microsoft.com/download/dotnet/10.0) +- **Visual Studio 2026** (Latest stable version) or **VS Code** with the C# Dev Kit extension +- A terminal you are comfortable with (PowerShell, bash, or the VS Code integrated terminal) + +You can verify your setup by running: + +```bash +node --version # v24.x (use latest stable) +ng version # Angular CLI 21.x +dotnet --version # 10.x +``` + +## Approach 1 — Manual Setup + +This approach gives you full control over every detail. It is the best choice if you want to understand how the pieces fit together or if you have specific architectural requirements. + +### Step 1: Create the Angular App + +Open a terminal and run: + +```bash +ng new MyApp.Client --style=scss --routing=true --ssr=false +cd MyApp.Client +ng serve +``` + +Navigate to `http://localhost:4200` — you should see the default Angular welcome page. + +### Step 2: Create the ASP.NET Core Web API + +Open a new terminal in the parent directory and create the API project: + +```bash +dotnet new webapi -n MyApp.Api --use-controllers +cd MyApp.Api +``` + +Let's add a simple endpoint to test the connection. Open `Controllers/WeatherForecastController.cs` — the template already includes a `GET /WeatherForecast` endpoint that returns random forecast data. We will use this for our first integration test. + +Run the API: + +```bash +dotnet run +``` + +The API will start on a port shown in the terminal output (e.g. `http://localhost:5266`). You can verify it by navigating to `http://localhost:{port}/WeatherForecast` in your browser. Take note of this port — you will need it for the proxy configuration in Step 4. + +### Step 3: Configure CORS + +By default, your Angular app on `localhost:4200` cannot call the API on `localhost:5001` because of the browser's same-origin policy. We need to enable CORS on the API side. + +Open `Program.cs` and add the following: + +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddControllers(); +builder.Services.AddOpenApi(); + +// Add CORS policy +builder.Services.AddCors(options => +{ + options.AddPolicy("Angular", policy => + { + policy.WithOrigins("http://localhost:4200") + .AllowAnyHeader() + .AllowAnyMethod(); + }); +}); + +var app = builder.Build(); + +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} + +app.UseHttpsRedirection(); + +// Use the CORS policy +app.UseCors("Angular"); + +app.UseAuthorization(); +app.MapControllers(); +app.Run(); +``` + +**Note:** This CORS configuration is for development only. In production, you should restrict the allowed origins to your actual domain. + +### Step 4: Set Up the Angular Proxy + +While CORS works, a cleaner approach during development is to use Angular's built-in proxy. This way, the Angular dev server forwards API requests to the backend, and you avoid CORS entirely. + +Create a file called `proxy.conf.json` in the root of your Angular project: + +```json +{ + "/WeatherForecast": { + "target": "http://localhost:5266", + "secure": false, + "changeOrigin": true + } +} +``` + +**Note:** Replace `5266` with the actual port your API is running on. You can find it in the terminal output when you run `dotnet run` — look for the line that says `Now listening on: http://localhost:XXXX`. Also, we are proxying the `/WeatherForecast` path directly because the default .NET template does not use an `/api` prefix. In a real project, you would typically add a common prefix like `/api` to all your controllers (using `[Route("api/[controller]")]`) and proxy that single prefix instead. + +Update `angular.json` to use the proxy. Find the `serve` section and add the `proxyConfig` option: + +```json +"serve": { + "options": { + "proxyConfig": "proxy.conf.json" + } +} +``` + +Now restart the Angular dev server with `ng serve`. Any request to `/WeatherForecast` from your Angular app will be forwarded to the .NET backend. + +### Step 5: Make the First API Call + +Let's update the root component to fetch weather data from the API. First, we need to configure `HttpClient`. Open `src/app/app.config.ts` and add `provideHttpClient()`: + +```typescript +import { ApplicationConfig } from '@angular/core'; +import { provideRouter } from '@angular/router'; +import { provideHttpClient } from '@angular/common/http'; + +import { routes } from './app.routes'; + +export const appConfig: ApplicationConfig = { + providers: [ + provideRouter(routes), + provideHttpClient() + ] +}; +``` + +Now open `src/app/app.ts` and update it: + +```typescript +import { Component, inject, OnInit, signal } from '@angular/core'; +import { HttpClient } from '@angular/common/http'; + +interface WeatherForecast { + date: string; + temperatureC: number; + temperatureF: number; + summary: string; +} + +@Component({ + selector: 'app-root', + templateUrl: './app.html', + styleUrl: './app.scss' +}) +export class App implements OnInit { + private http = inject(HttpClient); + forecasts = signal([]); + + ngOnInit() { + this.http.get('/WeatherForecast') + .subscribe(data => this.forecasts.set(data)); + } +} +``` + +Then update `src/app/app.html` with the template: + +```html +

Weather Forecast

+@if (forecasts().length > 0) { + + + + + + + + + + + @for (f of forecasts(); track f.date) { + + + + + + + } + +
DateTemp (C)Temp (F)Summary
{{ f.date }}{{ f.temperatureC }}{{ f.temperatureF }}{{ f.summary }}
+} +``` + +Save the file and check your browser. You should see the weather data rendered in a table. Your Angular frontend is now talking to your ASP.NET Core backend. + +## Approach 2 — Visual Studio Template + +If you prefer a faster start with less manual configuration, Visual Studio 2022 ships with a built-in **Angular + ASP.NET Core** project template. + +1. Open Visual Studio 2026 and select **Create a new project**. +2. Search for **"ASP.NET Core with Angular"** and select the template. +3. Configure the project name, location, and solution name. +4. On the next screen, select **.NET 10** as the target framework. +5. Click **Create**. + +Visual Studio generates a solution with two projects: + +- An **ASP.NET Core** backend with a sample `WeatherForecast` API. +- An **Angular** frontend with proxy configuration already wired up. + +Press **F5** to run the project. Both the backend and the frontend will start together, and you will see a working Angular app fetching data from the API. + +**What you get out of the box:** +- Pre-configured proxy (`proxy.conf.js`) +- HTTPS development certificate setup +- Integrated launch profiles for debugging both projects simultaneously + +**What you don't get:** +- Authentication / authorization +- Multi-tenancy +- Role management +- A production-ready UI framework + +This template is a great starting point for prototypes or simple applications. For enterprise projects, you will need to add these features yourself — or use a framework that includes them. But, be aware that this option may have problems time to time because some pf the NPM packages intorduce breaking changes and it takes time for maintainer team to release a working version. + +## Approach 3 — ASP.NET Zero + +[ASP.NET Zero](https://aspnetzero.com/) is a production-ready starter kit built on ASP.NET Core that supports **Angular**, **React**, and **MVC (Razor)** as frontend options. It is designed specifically for enterprise applications and includes dozens of features out of the box. + +Here is how to get started: + +1. Go to [aspnetzero.com](https://aspnetzero.com/) and sign up for a license. +2. Navigate to the **Download** page, select **Angular** as your frontend, and download the project. +3. Open the solution in Visual Studio or VS Code. +4. Update the database connection string in `appsettings.json`. +5. Run the `migrator` project to create and seed the database: + +```bash +cd src/MyProject.Migrator +dotnet run +``` + +6. Start the backend: + +```bash +cd src/MyProject.Web.Host +dotnet run +``` + +7. Start the Angular frontend: + +```bash +cd angular +yarn +yarn create-dynamic-bundles +yarn start +``` + +Navigate to `http://localhost:4200` and log in with the default admin credentials. You will see a fully working enterprise application. + +To run the project propertly, you can follow [Angular Getting Started Document](https://docs.aspnetzero.com/aspnet-core-angular/latest/Getting-Started-Angular). + +**What you get out of the box:** + +- **Authentication & Authorization:** Login, registration, two-factor authentication, social logins, LDAP/Active Directory integration — all pre-built and configurable. +- **Multi-Tenancy:** Host/tenant architecture with separate databases or shared database options. Tenant registration, subscription management, and edition management are built in. +- **Role & Permission Management:** A granular permission system with role-based and user-based authorization. +- **Organization Units:** Hierarchical organizational structure with the ability to assign users and roles per unit. +- **Audit Logging:** Every action is logged with user, timestamp, and change details. +- **Real-Time Notifications:** Built-in notification system with SignalR integration. +- **UI Theme:** A polished admin theme based on Metronic with responsive design, dark mode, and multiple layout options. +- **Power Tools:** A Visual Studio extension and a CLI tool that generates **entities, DTOs, application services, API controllers, Angular components, and unit tests** from a simple entity definition. Instead of writing CRUD code manually, you describe your entity and Power Tools generates everything. + +Let's see Power Tools in action. Say you want to add a `Product` entity to your application. You define the entity fields (Name, Price, Category, etc.) in Power Tools, click **Generate**, and it creates: + +- The `Product` entity and database migration +- `ProductAppService` with full CRUD operations +- `ProductDto` and `CreateProductDto` classes +- Angular components for listing, creating, and editing products +- Unit tests for the app service +- UI tests for your Angular pages + +What would take hours of boilerplate coding is done in under a minute. + +## Comparison + +Here is how the three approaches compare: + +| Feature | Manual Setup | VS Template | ASP.NET Zero | +|---|---|---|---| +| Setup time | 30-60 min | 5 min | 10 min | +| Authentication | You build it | You build it | Built-in | +| Authorization / Roles | You build it | You build it | Built-in | +| Multi-tenancy | You build it | You build it | Built-in | +| Organization units | You build it | You build it | Built-in | +| Audit logging | You build it | You build it | Built-in | +| UI theme | None | Basic | Metronic (production-ready) | +| Code generation tools | None | None | Power Tools | +| Real-time notifications | You build it | You build it | Built-in | +| Learning value | High | Medium | High | +| Flexibility | Full | Full | Full (source code included) | +| Cost | Free | Free | Licensed | + +**Bottom line:** If you are learning or building a simple prototype, the manual setup or VS template is perfect. If you are building an enterprise application and want to skip months of infrastructure work, ASP.NET Zero gives you a massive head start. + +## Common Issues and Solutions + +### CORS Errors + +**Symptom:** The browser console shows `Access to XMLHttpRequest has been blocked by CORS policy`. + +**Solution:** Make sure your `Program.cs` includes the CORS middleware and that `app.UseCors()` is called **before** `app.UseAuthorization()`. Also verify that the origin URL matches exactly (including the port number and protocol). + +```csharp +// Correct order +app.UseCors("Angular"); +app.UseAuthorization(); +``` + +### Proxy Not Working + +**Symptom:** API calls return 404 or the Angular app tries to serve the request itself. + +**Solution:** Double-check the `proxy.conf.json` path in `angular.json`. Make sure the `target` URL matches the port your API is running on. Restart `ng serve` after any proxy configuration change — the proxy config is only read at startup. + +### SSL Certificate Errors + +**Symptom:** `ERR_CERT_AUTHORITY_INVALID` or proxy shows `UNABLE_TO_VERIFY_LEAF_SIGNATURE`. + +**Solution:** For development, set `"secure": false` in your `proxy.conf.json`. This tells the Angular dev server to accept self-signed certificates. Alternatively, trust the .NET development certificate: + +```bash +dotnet dev-certs https --trust +``` + +### Angular CLI Version Mismatch + +**Symptom:** Build errors or unexpected behavior after creating the project. + +**Solution:** Make sure your global Angular CLI version matches the version in the project's `package.json`. You can check with `ng version` and update with: + +```bash +npm install -g @angular/cli@19 +``` + +## Next Steps + +Now that your Angular + ASP.NET Core project is up and running, here are some next steps depending on which approach you chose: + +- **Add authentication:** If you went with the manual setup or VS template, check out the [ASP.NET Core Identity documentation](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/identity) to add login and registration. +- **Explore ASP.NET Zero:** If you are interested in the enterprise approach, [contact](https://aspnetzero.com/contact) ASP.NET Zero Team and explore the [documentation](https://docs.aspnetzero.com/). The Angular getting started guide will have you running in under 10 minutes. +- **Try Power Tools:** If you are already using ASP.NET Zero, generate your first entity with [Power Tools](https://docs.aspnetzero.com/development-guide/rad-tool) and see how much time it saves. + +Building enterprise applications is hard. Choosing the right foundation makes it significantly easier. Whether you start from scratch or stand on the shoulders of a mature framework, Angular and ASP.NET Core together give you a rock-solid stack for 2026 and beyond. diff --git a/blog-posts/en/2026-04-02-angular-aspnet-core-getting-started-guide/cover.png b/blog-posts/en/2026-04-02-angular-aspnet-core-getting-started-guide/cover.png new file mode 100644 index 00000000..f0c4815e Binary files /dev/null and b/blog-posts/en/2026-04-02-angular-aspnet-core-getting-started-guide/cover.png differ diff --git a/docs/en/Deployment-Angular-Publish-Azure.md b/docs/en/Deployment-Angular-Publish-Azure.md index 7653ffaf..50423ba0 100644 --- a/docs/en/Deployment-Angular-Publish-Azure.md +++ b/docs/en/Deployment-Angular-Publish-Azure.md @@ -86,15 +86,15 @@ Select "**your-host-app-service-name**" and click "**OK**", then click "**Publis Here are the quick steps to publish the **AngularUI** to the Azure -- Run the `yarn` command to restore packages -- Run the `npm run publish` command to publish Angular app. +- Run the `pnpm install` command to restore packages +- Run the `pnpm run publish` command to publish Angular app. - Copy the web.config file that is placed in **angular** folder to **dist** folder - Configure the **angular/dist/assets/appconfig.json** with your production URLs. - Upload all files under "angular/dist" folder to your website on Azure created for the Angular UI. ### Prepare The Publish Folder -Run the `yarn` command to restore packages and run the `npm run publish` to publish the Angular app. +Run the `pnpm install` command to restore packages and run the `pnpm run publish` to publish the Angular app. ### Copy the web.config diff --git a/docs/en/Deployment-Angular.md b/docs/en/Deployment-Angular.md index 38cdc7c7..d3608d68 100644 --- a/docs/en/Deployment-Angular.md +++ b/docs/en/Deployment-Angular.md @@ -4,10 +4,10 @@ ASP.NET Zero depends on [angular-cli](https://cli.angular.io/) for development & deployment. It uses angular-cli commands to build and publish its Angular client application. ASP.NET Zero also minifies and bundles some assets (JS and CSS files) using [gulp](https://gulpjs.com/) before publishing the Angular client application since those assets are loaded dynamically at runtime. In order to publish the Angular client application below commands must be run respectively. -1. run ```yarn``` command in the root directory of Angular project. -2. run ```npm run publish``` command in the root directory of Angular project. +1. run ```pnpm install``` command in the root directory of Angular project. +2. run ```pnpm run publish``` command in the root directory of Angular project. -In the Web.Host project, run ```npm run create-bundles``` to bundle and minify JS and CSS files before final deployment. +In the Web.Host project, run ```pnpm run create-bundles``` to bundle and minify JS and CSS files before final deployment. ASP.NET Zero also provides a merged solution for ASP.NET Core & Angular version. In that solution, Angular client side application is included in the server side Host project. Those two applications, server side API project and Angular client side application, can be published at once and can be hosted together under the same website. diff --git a/docs/en/Deployment-Mvc-Core-Azure.md b/docs/en/Deployment-Mvc-Core-Azure.md index 67ea27a0..c321d94b 100644 --- a/docs/en/Deployment-Mvc-Core-Azure.md +++ b/docs/en/Deployment-Mvc-Core-Azure.md @@ -30,15 +30,15 @@ On Azure portal, go to SQL databases menu and create a new empty database. If yo Here are the quick steps to publish the **Web.Mvc Application** to the Azure. -- Run the ```yarn``` command in the root directory of MVC project. -- Run the `npm run build` to bundle and minify the js/css files +- Run the ```pnpm install``` command in the root directory of MVC project. +- Run the `pnpm run build` to bundle and minify the js/css files - Run the migrations on the Azure - Configure the **.Web.Mvc/appsettings.production.json** - Publish the application to Azure ### Run the `npm run build` -First run the ```yarn``` command in the root directory of MVC project to install client side dependencies. Then, run the `npm run build` to bundle and minify the script and style files. +First run the ```pnpm install``` command in the root directory of MVC project to install client side dependencies. Then, run the `pnpm run build` to bundle and minify the script and style files. ### Run Migrations on The Azure @@ -98,7 +98,7 @@ Since we migrated the database when deploying Admin application, we will not do ### NPM Packages -First run the ```yarn``` command in the root directory of MVC project to install client side dependencies. Then, run the `npm run build` to bundle and minify the script and style files. +First run the ```pnpm install``` command in the root directory of MVC project to install client side dependencies. Then, run the `pnpm run build` to bundle and minify the script and style files. ### Configure the appsettings.production.json diff --git a/docs/en/Deployment-React-Docker.md b/docs/en/Deployment-React-Docker.md index c59dcb0d..613df7b7 100644 --- a/docs/en/Deployment-React-Docker.md +++ b/docs/en/Deployment-React-Docker.md @@ -6,14 +6,14 @@ ASP.NET Zero solution has a **build folder** which contains scripts to **build & * Node.js (LTS version recommended) * Docker Desktop installed and running -* Packages installed (`yarn` or `npm install`) +* Packages installed (`pnpm install` or `npm install`) ## Building the React Application Before creating a Docker image, build the React application: ```bash -yarn build +pnpm build # or npm run build ``` diff --git a/docs/en/Deployment-React-Publish-Azure.md b/docs/en/Deployment-React-Publish-Azure.md index f8afda41..e2a11473 100644 --- a/docs/en/Deployment-React-Publish-Azure.md +++ b/docs/en/Deployment-React-Publish-Azure.md @@ -100,7 +100,7 @@ This URL should point to your published Host API application. Run the following commands to build the React application: ```bash -yarn && yarn build +pnpm install && pnpm build # or npm install && npm run build ``` diff --git a/docs/en/Deployment-React-Publish-IIS.md b/docs/en/Deployment-React-Publish-IIS.md index d65aaa70..1d98476c 100644 --- a/docs/en/Deployment-React-Publish-IIS.md +++ b/docs/en/Deployment-React-Publish-IIS.md @@ -41,7 +41,7 @@ The React application is built using Vite and can be deployed as static files to VITE_API_BASE_URL=https://your-host-api-url ``` -2. Run `yarn build` or `npm run build`. This command outputs the production build to the `dist` folder. +2. Run `pnpm build` or `npm run build`. This command outputs the production build to the `dist` folder. 3. Copy all files from the `dist` folder to your IIS website directory (for example: `C:\inetpub\wwwroot\reactwebsite`). diff --git a/docs/en/Deployment-React.md b/docs/en/Deployment-React.md index c8feeae2..28ead18f 100644 --- a/docs/en/Deployment-React.md +++ b/docs/en/Deployment-React.md @@ -8,8 +8,8 @@ ASP.NET Zero React UI is built using [Vite](https://vite.dev/) as the build tool To build the React application for production, run the following commands in the root directory of the React project: -1. Run `yarn` or `npm install` to install dependencies. -2. Run `yarn build` or `npm run build` to create a production build. +1. Run `pnpm install` or `npm install` to install dependencies. +2. Run `pnpm build` or `npm run build` to create a production build. The build output will be placed in the `dist/` folder, ready for deployment to any static file server. @@ -29,7 +29,7 @@ ASP.NET Zero also provides a merged solution where the React client-side applica To publish the merged solution: -1. Run `yarn build` or `npm run build` in the React project to build the client application. +1. Run `pnpm build` or `npm run build` in the React project to build the client application. 2. Run `dotnet publish -c Release` in the root directory of the `*.Host` project. See the [dotnet publish documentation](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-publish) for additional parameters. 3. When the publish is complete, ensure the React build output is copied to the `wwwroot` folder of the published Host application. @@ -47,7 +47,7 @@ Vite automatically applies the following optimizations for production builds: You can preview the production build locally by running: ```bash -yarn preview +pnpm preview # or npm run preview ``` diff --git a/docs/en/Development-React-Docker.md b/docs/en/Development-React-Docker.md index 946bd0bc..2ed668d1 100644 --- a/docs/en/Development-React-Docker.md +++ b/docs/en/Development-React-Docker.md @@ -56,7 +56,7 @@ The React UI is a client-side application that can be run in two ways during dev Run the React UI using the Vite development server: ```bash -yarn && yarn dev +pnpm install && pnpm dev # or npm install && npm run dev ``` diff --git a/docs/en/Getting-Started-Angular-Merged.md b/docs/en/Getting-Started-Angular-Merged.md index c3c4bd99..0bc0bf3b 100644 --- a/docs/en/Getting-Started-Angular-Merged.md +++ b/docs/en/Getting-Started-Angular-Merged.md @@ -18,7 +18,7 @@ Select **ASP.NET Core & Angular** as Project Type and fill other required fields - [Visual Studio 2017 (v15.9.0+)](https://www.visualstudio.com) (for backend ASP.NET Core application) - [Node.js 6.9+ with NPM 3.10+](https://nodejs.org/en/download/) -- [Yarn v1.x](https://classic.yarnpkg.com/lang/en/) +- [pnpm](https://pnpm.io/installation) ## ASP.NET Core Application @@ -89,16 +89,16 @@ For example when you navigate **Swagger UI**, you will see following page: Navigate to the root folder of ***.Web.Host** project, open a command line and run the following command to restore the packages: ```bash -yarn +pnpm install ``` Then, run the following command to create dynamic bundles *(This is only required for the first time when you download the project or when you update dynamic bundles)*: ```bash -npm run create-dynamic-bundles +pnpm run create-dynamic-bundles ``` -We use [yarn v1.x](https://classic.yarnpkg.com/lang/en/) because NPM has some problems; It is slow and can not consistently resolve dependencies. Yarn solves those problems and it is compatible to NPM as well. +We use [pnpm](https://pnpm.io/) for fast, disk-efficient and deterministic dependency resolution. The pinned version is declared in `package.json` under the `packageManager` field, so [Corepack](https://nodejs.org/api/corepack.html) will activate the correct pnpm version automatically. ### Running The Application diff --git a/docs/en/Getting-Started-Angular.md b/docs/en/Getting-Started-Angular.md index 5af5f309..4c16728e 100644 --- a/docs/en/Getting-Started-Angular.md +++ b/docs/en/Getting-Started-Angular.md @@ -26,7 +26,7 @@ If you have selected this option, please follow [Getting Started](Getting-Starte - [Visual Studio 2017 (v15.9.0+)](https://www.visualstudio.com) (for backend ASP.NET Core application) - [Node.js 16.x+ with NPM 8.x+](https://nodejs.org/en/download/) -- [Yarn v1.x](https://classic.yarnpkg.com/lang/en/) +- [pnpm](https://pnpm.io/installation) ## ASP.NET Core Application @@ -97,16 +97,16 @@ For example when you navigate **Swagger UI**, you will see following page: Navigate to the **angular** folder, open a command line and run the following command to restore the packages: ```bash -yarn +pnpm install ``` Then, run the following command to create dynamic bundles *(This is only required for the first time when you download the project or when you update dynamic bundles)*: ```bash -npm run create-dynamic-bundles +pnpm run create-dynamic-bundles ``` -We use [yarn v1.x](https://classic.yarnpkg.com/lang/en/) because NPM has some problems; It is slow and can not consistently resolve dependencies. Yarn solves those problems and it is compatible to NPM as well. +We use [pnpm](https://pnpm.io/) for fast, disk-efficient and deterministic dependency resolution. The pinned version is declared in `package.json` under the `packageManager` field, so [Corepack](https://nodejs.org/api/corepack.html) will activate the correct pnpm version automatically. ### Running The Application diff --git a/docs/en/Getting-Started-Core.md b/docs/en/Getting-Started-Core.md index d39fb438..eb509795 100644 --- a/docs/en/Getting-Started-Core.md +++ b/docs/en/Getting-Started-Core.md @@ -14,17 +14,17 @@ Select **ASP.NET Core & jQuery** as Project Type and fill other required fields. - [Visual Studio 2017 (v15.9.0+)](https://www.visualstudio.com) - [Node.js 16.x+ with NPM 8.x+](https://nodejs.org/en/download/) -- [Yarn v1.x](https://classic.yarnpkg.com/lang/en/) +- [pnpm](https://pnpm.io/installation) ## Configure The Project -Before opening the solution, open a command prompt, navigate to root directory of **\*.Web.Mvc** project and run "**yarn**" command to install client side dependencies. +Before opening the solution, open a command prompt, navigate to root directory of **\*.Web.Mvc** project and run "**pnpm install**" command to install client side dependencies. ```bash -yarn +pnpm install ``` -**Important Notice:** Installing client side npm dependencies using **yarn** before opening the solution will decrease project opening & building time dramatically. +**Important Notice:** Installing client side npm dependencies using **pnpm** before opening the solution will decrease project opening & building time dramatically. Open the **\*.Web.sln** solution in **Visual Studio**. If you want to work on only MAUI project, open **\*.Maui.sln** solution. If you want to work on both MAUI and Web projects, open **\*.All.sln** solution. diff --git a/docs/en/Getting-Started-MacOSX.md b/docs/en/Getting-Started-MacOSX.md index b68b6892..6ab9354e 100644 --- a/docs/en/Getting-Started-MacOSX.md +++ b/docs/en/Getting-Started-MacOSX.md @@ -7,16 +7,16 @@ Download an ASP.NET CORE & Angular project with .NET Core framework as described - Visual Studio for Mac: [https://visualstudio.microsoft.com/vs/mac/](https://visualstudio.microsoft.com/vs/mac/) - .Net core SDK: [https://www.microsoft.com/net/download/macos](https://www.microsoft.com/net/download/macos) - - Yarn v1.x [https://classic.yarnpkg.com/en/docs/install#mac-stable](https://classic.yarnpkg.com/en/docs/install#mac-stable) + - pnpm [https://pnpm.io/installation#using-a-standalone-script](https://pnpm.io/installation#using-a-standalone-script) - NVM with node version 8.11.1+: [https://github.com/creationix/nvm](https://github.com/creationix/nvm) - Angular-cli ([https://cli.angular.io/](https://cli.angular.io/)) ## Restoring Packages -In the terminal, go to base_folder/angular and run the `yarn` command: +In the terminal, go to base_folder/angular and run the `pnpm install` command: ```bash -yarn +pnpm install ``` ## Configuration & Build diff --git a/docs/en/Getting-Started-React.md b/docs/en/Getting-Started-React.md index b414ea70..974a21a1 100644 --- a/docs/en/Getting-Started-React.md +++ b/docs/en/Getting-Started-React.md @@ -20,7 +20,7 @@ Select **ASP.NET Core & React** as Project Type and fill other required fields. - [Visual Studio 2022 (v17.10+)](https://www.visualstudio.com) (for backend ASP.NET Core application) - [Node.js 18.x+ with NPM 8.x+](https://nodejs.org/en/download/) -- [Yarn v1.x](https://classic.yarnpkg.com/lang/en/) +- [pnpm](https://pnpm.io/installation) ## ASP.NET Core Application @@ -88,24 +88,20 @@ For example when you navigate **Swagger UI**, you will see following page: ### Restore Packages -Navigate to the **react** folder, open a command line and run one of the following commands to restore the packages: +Navigate to the **react** folder, open a command line and run the following command to restore the packages: ```bash -yarn -# or -npm install +pnpm install ``` -We recommend using [yarn v1.x](https://classic.yarnpkg.com/lang/en/) for faster and more consistent dependency resolution, but npm works as well. +We use [pnpm](https://pnpm.io/) for faster and more deterministic dependency resolution. The pinned version is declared in `package.json` under the `packageManager` field, so [Corepack](https://nodejs.org/api/corepack.html) will activate the correct pnpm version automatically. NPM also works if you prefer it (`npm install`). ### Running The Application -Run one of the following commands in the command line: +Run the following command in the command line: ```bash -yarn dev -# or -npm run dev +pnpm dev ``` Once the application compiled, you can browse in your browser. diff --git a/docs/en/Infrastructure-Angular-Npm-Packages.md b/docs/en/Infrastructure-Angular-Npm-Packages.md index 773645a3..d7261514 100644 --- a/docs/en/Infrastructure-Angular-Npm-Packages.md +++ b/docs/en/Infrastructure-Angular-Npm-Packages.md @@ -1,3 +1,3 @@ # NPM Packages -ASP.NET Zero solution supports both [Yarn v1.x](https://classic.yarnpkg.com/lang/en/) and [NPM](https://www.npmjs.com/) to obtain front end library dependencies (like Angular and Bootstrap). We suggest to use yarn because NPM has some problems, yarn solves those problems and it is compatible with NPM as well. You can easily add, update or remove packages on yarn's command line interface. \ No newline at end of file +ASP.NET Zero solution uses [pnpm](https://pnpm.io/) (preferred) to obtain front end library dependencies (like Angular and Bootstrap). [NPM](https://www.npmjs.com/) is also supported. We suggest using pnpm because it is fast, disk-efficient, and deterministic. The pinned pnpm version is declared in `package.json` under the `packageManager` field, so [Corepack](https://nodejs.org/api/corepack.html) will activate the correct version automatically. You can easily add, update or remove packages on pnpm's command line interface. \ No newline at end of file diff --git a/docs/en/Infrastructure-React-Bundling-Minifying-Compiling.md b/docs/en/Infrastructure-React-Bundling-Minifying-Compiling.md index 724e1d55..265a22af 100644 --- a/docs/en/Infrastructure-React-Bundling-Minifying-Compiling.md +++ b/docs/en/Infrastructure-React-Bundling-Minifying-Compiling.md @@ -7,7 +7,7 @@ ASP.NET Zero uses [Vite](https://vitejs.dev/) to build the React application. Vi During development, run the following command to start the Vite development server: ```bash -yarn dev +pnpm dev # or npm run dev ``` @@ -19,7 +19,7 @@ Vite provides fast Hot Module Replacement (HMR) and serves your assets without b For production, run the following command: ```bash -yarn build +pnpm build # or npm run build ``` @@ -37,7 +37,7 @@ This command will: To preview the production build locally before deployment, you can use: ```bash -yarn preview +pnpm preview # or npm run preview ``` diff --git a/docs/en/Infrastructure-React-Npm-Packages.md b/docs/en/Infrastructure-React-Npm-Packages.md index f018fabd..b1df191e 100644 --- a/docs/en/Infrastructure-React-Npm-Packages.md +++ b/docs/en/Infrastructure-React-Npm-Packages.md @@ -1,17 +1,17 @@ # Package Management -ASP.NET Zero React UI uses [Yarn](https://classic.yarnpkg.com/) or [NPM](https://www.npmjs.com/) to manage front-end library dependencies (like React and Ant Design). You can easily add, update, or remove packages using the command line interface. +ASP.NET Zero React UI uses [pnpm](https://pnpm.io/) (preferred) or [NPM](https://www.npmjs.com/) to manage front-end library dependencies (like React and Ant Design). The pinned pnpm version is declared in `package.json` under the `packageManager` field, so [Corepack](https://nodejs.org/api/corepack.html) will activate the correct version automatically. You can easily add, update, or remove packages using the command line interface. ## Common Commands -| Action | Yarn | NPM | +| Action | pnpm | NPM | |--------|------|-----| -| Install all dependencies | `yarn` | `npm install` | -| Add a new package | `yarn add package-name` | `npm install package-name` | -| Add a dev dependency | `yarn add package-name --dev` | `npm install package-name --save-dev` | -| Update packages | `yarn upgrade` | `npm update` | -| Remove a package | `yarn remove package-name` | `npm uninstall package-name` | +| Install all dependencies | `pnpm install` | `npm install` | +| Add a new package | `pnpm add package-name` | `npm install package-name` | +| Add a dev dependency | `pnpm add -D package-name` | `npm install package-name --save-dev` | +| Update packages | `pnpm update` | `npm update` | +| Remove a package | `pnpm remove package-name` | `npm uninstall package-name` | ## Package.json -Dependencies are defined in [package.json](../package.json). After modifying dependencies, run `yarn` or `npm install` to update your `node_modules` folder. +Dependencies are defined in [package.json](../package.json). After modifying dependencies, run `pnpm install` or `npm install` to update your `node_modules` folder. diff --git a/docs/en/Infrastructure-React-Vite.md b/docs/en/Infrastructure-React-Vite.md index 6244ce3b..ce56890a 100644 --- a/docs/en/Infrastructure-React-Vite.md +++ b/docs/en/Infrastructure-React-Vite.md @@ -7,7 +7,7 @@ ASP.NET Zero React UI uses [Vite](https://vitejs.dev/) for development and produ To run the application in development mode, open a terminal and run: ```bash -yarn dev +pnpm dev # or npm run dev ``` @@ -19,7 +19,7 @@ Once compiled and ready, you can open the application in your browser at **Note:** The ASP.NET Zero MVC project now uses [pnpm](https://pnpm.io/) (pinned via the `packageManager` field in `package.json`) instead of Yarn. The simplest approach on Azure Pipelines is a **Command Line** task that enables Corepack and runs `pnpm install`, since Corepack ships with Node.js 16.10+ and activates the pinned pnpm version automatically. +1. #### **Execute pnpm install Task** -Click on the **Get it free** button to install the necessary extension for your organization. - -![Add new task](images/azure-pipelines-add-marketplace-yarn.png) - -1. #### **Execute Yarn Task** - - For the MVC project, we have to run `yarn` command in the `src/MyPortalDemo.Web.Mvc` folder. To do this click the `Show asisstant` icon on top of the task list. + For the MVC project, we have to run `pnpm install` in the `src/MyPortalDemo.Web.Mvc` folder. To do this click the `Show assistant` icon on top of the task list. ![Add new task](images/azure-pipelines-show-assistant.png) - Write **yarn** into the search textbox and click on the **Yarn task** to install this new Yarn task. + In the Tasks panel, search for **Command Line** and select the **Command line** task. Place it right after the **Build** step. - ![Install yarn](images/azure-pipelines-add-yarn-task.png) + ![Add Command Line task for pnpm](images/azure-pipelines-add-pnpm-task.png) + Use the following script and set the **Working Directory** (under **Advanced**) to `src/MyPortalDemo.Web.Mvc`: + + ```bash + corepack enable + pnpm install --frozen-lockfile + ``` - After adding it, the new Yarn task is placed at the end. Move it after the **Build** step. Then, enter `src/MyPortalDemo.Web.Mvc` in the Project Directory. This step is completed. + ![Configure pnpm install task](images/azure-pipelines-add-pnpm-task-2.png) - ![Yarn task](images/azure-pipelines-add-yarn-task2.png) + This installs the pnpm version pinned in `package.json` and restores client-side dependencies. This step is completed. @@ -167,24 +168,24 @@ Click on the **Get it free** button to install the necessary extension for your -2. #### **NPM Run Build Task** +2. #### **pnpm run build Task** - To add NPM Run Build task, write `command line` to the search textbox. Click the **Add** button of **Command Line** item. + To add the production build task, write `command line` to the search textbox. Click the **Add** button of **Command Line** item. ![Add command line task](images/azure-pipelines-add-npm-run-build-task.png) - It will append it after right after the **Yarn** task. If it comes to the end, you need to move it after **Yarn** task. + It will append it right after the **pnpm install** task. If it comes to the end, you need to move it after the **pnpm install** task. + Use the following script and set the **Working Directory** (under **Advanced**) to `src/MyPortalDemo.Web.Mvc`: ```bash - cd src/MyPortalDemo.Web.Mvc - npm run build + pnpm run build ``` - ![NPM Run Build Task](images/azure-pipelines-add-npm-run-build-task2.png) + ![pnpm run build Task](images/azure-pipelines-add-pnpm-task-3.png) @@ -216,7 +217,7 @@ After clicking the **Save** button on the toolbar, press the **Run** button. The -So far, we have created a pipeline to get our project from GitHub, build, yarn, NPM run build, test and publish. The next step is copying the publish output to Azure App Service. +So far, we have created a pipeline to get our project from GitHub, build, pnpm install, pnpm run build, test and publish. The next step is copying the publish output to Azure App Service. **Before starting this step, we assume that you have already created a web app on Azure App Services and set up your database**. diff --git a/docs/en/images/azure-pipelines-add-pnpm-task-2.png b/docs/en/images/azure-pipelines-add-pnpm-task-2.png new file mode 100644 index 00000000..f199376c Binary files /dev/null and b/docs/en/images/azure-pipelines-add-pnpm-task-2.png differ diff --git a/docs/en/images/azure-pipelines-add-pnpm-task-3.png b/docs/en/images/azure-pipelines-add-pnpm-task-3.png new file mode 100644 index 00000000..7c85080d Binary files /dev/null and b/docs/en/images/azure-pipelines-add-pnpm-task-3.png differ diff --git a/docs/en/images/azure-pipelines-add-pnpm-task.png b/docs/en/images/azure-pipelines-add-pnpm-task.png new file mode 100644 index 00000000..233ebced Binary files /dev/null and b/docs/en/images/azure-pipelines-add-pnpm-task.png differ