@nobertdev/bc-intergration-starter

Interactive CLI for generating an ASP.NET Core + React starter configured for Microsoft Dynamics 365 Business Central on-premises integration.

Documentation

Read the complete installation, configuration, authentication, and troubleshooting guide at bc-integration-documentation.vercel.app.

The generated project follows a familiar Controller → Service → OData/SOAP integration structure. It includes a Visual Studio solution, a React client, Business Central connection helpers, optional JWT authentication, optional sample endpoints, and a Windows launcher for starting the API and client together.

Features

• ASP.NET Core 8, 9, or 10 based on compatible SDKs installed on the computer
• React and TypeScript with Vite
• Full Business Central OData company URL and SOAP codeunit URL configuration
• NTLM, Windows Negotiate, Windows process identity, or NavUserPassword authentication for BC
• Optional JWT bearer protection
• Active Directory or Business Central LoginAsJson user authentication
• Scalar API documentation
• Optional sample OData and dropdown endpoints
• Tailwind CSS, shadcn/ui, and TanStack Query ready to use
• Visual Studio solution containing server and client projects
• run.cmd for starting the API, React client, and browser on Windows

Requirements

• Node.js 22.13.0 or later
• npm
• A supported .NET SDK: 8, 9, or 10
• Access to the Business Central OData and SOAP services used by the generated application
• Visual Studio with Microsoft WCF Web Service Reference support for generating the NAVWS proxy

Quick start

Run the latest version without installing it globally:

npx @nobertdev/bc-intergration-starter@latest

You can also install the command globally:

npm install --global @nobertdev/bc-intergration-starter
bc-intergration-starter

The CLI creates the new project in the current directory. Existing destination folders are never overwritten.

Prompts

The interactive flow asks for:

| Setting | Available choices | | ------------------------------ | ------------------------------------------------------------------------------ | | Project name | Lowercase npm-style name, such as staff-portal | | Target .NET version | Compatible installed SDK versions supported by the templates | | API hosting | Windows/IIS or Linux/container | | BC service-tier authentication | NTLM, Windows Negotiate, Windows process identity, or Basic over HTTPS | | OData URL | Complete company URL ending in / | | Codeunit URL | Complete published SOAP codeunit URL | | API protection | JWT bearer or configure later | | User authentication | Active Directory or Business Central LoginAsJson; shown when JWT is selected | | API documentation | Include Scalar documentation | | Sample endpoint | Include a sample OData endpoint and published page name | | Dropdown endpoint | Include the team-style dropdown endpoint | | Frontend libraries | Tailwind CSS, shadcn/ui, and TanStack Query |

Example Business Central URLs:

http://bc-server:9048/BC/ODataV4/Company('Example Company')/
http://bc-server:9047/BC/WS/Example%20Company/Codeunit/PortalIntegration

The CLI asks for complete URLs and does not ask separately for a Business Central service instance.

Non-interactive usage

Accept the defaults and choose the output directory:

npx @nobertdev/bc-intergration-starter@latest staff-portal --yes --output ./projects

Generate from a JSON configuration file:

npx @nobertdev/bc-intergration-starter@latest --config starter.json --output ./projects

Example starter.json:

{
  "name": "staff-portal",
  "framework": "10.0",
  "hosting": "windows",
  "bcAuth": "ntlm",
  "odataUrl": "http://bc.example.internal:9048/BC/ODataV4/Company('Example')/",
  "codeunitUrl": "http://bc.example.internal:9047/BC/WS/Example/Codeunit/MyCodeunit",
  "apiAuth": "jwt",
  "authenticationMethod": "bc",
  "docs": true,
  "sample": true,
  "sampleEntity": "Customers",
  "dropdown": true,
  "tailwind": true,
  "shadcn": true,
  "tanstackQuery": true
}

Use "authenticationMethod": "ad" for Active Directory or "bc" for the Business Central LoginAsJson flow. This option is used only when apiAuth is "jwt".

Run the following command for all CLI options:

npx @nobertdev/bc-intergration-starter@latest --help

Generated project

staff-portal/
├── staff-portal.sln
├── run.cmd
├── bc-team-starter.json
├── server/
│   ├── Controllers/
│   ├── DTOs/
│   ├── Extensions/
│   ├── Interfaces/
│   ├── Models/
│   ├── Services/
│   ├── Program.cs
│   ├── Server.csproj
│   ├── appsettings.json
│   └── appsettings.Development.json
└── client/
    ├── src/
    ├── public/
    ├── components.json
    └── package.json

server/appsettings.json contains only:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Development URLs, connection settings, JWT settings, and optional Active Directory settings are written to server/appsettings.Development.json.

Authentication modes

Business Central service-tier authentication controls how the generated server connects to BC for OData and SOAP calls. API protection controls how application users authenticate to the generated API.

When Active Directory is selected, POST /api/account/login accepts userId and password, validates the credentials using LDAP or LDAPS, and returns a JWT bearer token.

When Business Central authentication is selected, the same endpoint accepts email and password. The generated service calls LoginAsJsonAsync, reads the base64 password salt and hash returned by BC, verifies the supplied password with HMACSHA512, and returns a JWT bearer token.

After generation

1. Open <project-name>.sln in Visual Studio.
2. Add a Microsoft WCF Web Service Reference to the server project using the codeunit URL with ?wsdl appended.
3. Name the connected service namespace NAVWS.
4. If Visual Studio generates a different client class name, update the single client type used by server/Models/Credentials.cs.
5. Configure the BC service account through server/appsettings.Development.json, environment variables, or user secrets.
6. When JWT is enabled, set a random TokenKey containing at least 64 UTF-8 bytes.
7. Run npm install inside client.
8. Start the server with its http launch profile or run run.cmd on Windows.

The generator intentionally does not restore or build the ASP.NET Core project. The server can have build errors until its project-specific NAVWS connected service has been generated.

When Scalar is enabled, the launch profile opens http://localhost:5080/scalar. The ASP.NET Core SPA proxy opens a separate command window for the Vite client on Windows.

Development

Clone the repository and work from the package directory:

git clone https://github.com/NOBERT167/bc-intergration-starter.git
cd bc-intergration-starter/team-style-starter
npm install
npm test
npm start

Inspect the exact files that npm will publish:

npm run pack:check

Security

Do not put Business Central passwords, Active Directory passwords, JWT signing keys, or production URLs in generator configuration files committed to source control. Use environment variables, .NET user secrets, or the deployment platform's secret store.

License

MIT © Nobert.Dev