dataverse-utilities
Advanced tools
TypeScript utilities for Microsoft Dataverse with Vite development plugins and testing support
A modern TypeScript library providing utilities for working with Microsoft Dataverse, including Vite development plugins and testing utilities.
⚠️ CAUTION: AI-Generated Code
This project was developed using AI assistance (Claude Code). Users should evaluate the code thoroughly before production use.
/api/data calls to your Dataverse instancenpm install dataverse-utilities
This library uses @azure/identity for Azure authentication and validator for URL validation.
The main library provides authentication and testing utilities for Microsoft Dataverse development.
import { setupDataverse } from 'dataverse-utilities/testing'
await setupDataverse({
dataverseUrl: 'https://yourorg.crm4.dynamics.com'
})
For Vite-based applications, use the Vite plugin for seamless Dataverse integration during development:
// vite.config.ts
import { defineConfig, loadEnv } from "vite";
import react from "@vitejs/plugin-react";
import { createDataverseConfig } from "dataverse-utilities/vite";
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), '');
const config = createDataverseConfig({
dataverseUrl: env.VITE_DATAVERSE_URL,
});
return {
...config,
plugins: [react(), ...config.plugins],
};
});
Alternative (server-only proxy):
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { createDataverseConfig } from 'dataverse-utilities/vite'
export default defineConfig({
plugins: [react()],
server: {
proxy: createDataverseConfig({
dataverseUrl: "https://yourorg.crm4.dynamics.com"
}).server.proxy
}
})
This automatically configures:
/api/data/* requests to your Dataverse instanceIn your application code:
// No imports needed - just use fetch() normally
const response = await fetch('/api/data/v9.1/accounts?$select=name&$top=5')
const data = await response.json()
The plugin handles authentication automatically during development.
The main library exports are currently minimal - add your own utilities here as needed.
dataverse-utilities/vite)createDataverseConfig(options: DataverseViteOptions): DataverseViteConfigCreates a complete Vite configuration with Dataverse proxy and authentication plugin.
Options:
dataverseUrl: Required HTTPS Dataverse URLtokenRefreshInterval: Optional token refresh interval (default: 50 minutes)enableConsoleLogging: Optional console logging (default: true)proxyPath: Optional proxy path pattern (default: '^/api/data')customProxyOptions: Optional additional proxy configurationskipAuthentication: Optional skip auth plugin (default: false)additionalPaths: Optional additional proxy pathsReturns: Configuration object with server.proxy and plugins for Vite
createDataverseConfigWithDefaults(dataverseUrl?, overrides?): DataverseViteConfigCreates Dataverse configuration with smart defaults, supporting environment variables.
Parameters:
dataverseUrl: Optional URL (falls back to VITE_DATAVERSE_URL env var)overrides: Optional configuration overridescreateAuthPlugin(options) - Create just the authentication plugincreateDataverseProxy(options) - Create just the proxy configurationcreateAdvancedDataverseProxy(options) - Create proxy with multiple patternsThis library is designed for development and testing environments only. Do NOT use in production.
The dataverse-utilities/testing module provides secure utilities for integration testing with Microsoft Dataverse. It automatically handles authentication via Azure CLI and provides a clean setup pattern for test environments.
npm install dataverse-utilities
Choose one of these setup approaches:
Option 1: Global setup file (recommended for most projects)
In your test setup file (e.g., src/test/setup.ts or vitest.config.ts setup):
import { setupDataverse } from 'dataverse-utilities/testing';
await setupDataverse({
dataverseUrl: 'https://yourorg.crm4.dynamics.com'
});
Option 2: Per-test setup (for more control)
In individual test files using beforeAll or beforeEach:
import { beforeAll, describe, it } from 'vitest';
import { setupDataverse } from 'dataverse-utilities/testing';
describe('Dataverse Integration', () => {
beforeAll(async () => {
await setupDataverse({
dataverseUrl: 'https://yourorg.crm4.dynamics.com'
});
});
it('fetches data', async () => {
const response = await fetch('/api/data/v9.1/accounts?$top=1');
// ... test code
});
});
Important: setupDataverse is async and must be awaited. Choose either global setup OR per-test setup, not both.
No imports needed - just use fetch() normally:
// integration.test.ts
import { describe, it, expect } from 'vitest';
describe('Dataverse Integration', () => {
it('fetches accounts', async () => {
// Library automatically adds auth headers and URL prefix
const response = await fetch('/api/data/v9.1/accounts?$select=name,emailaddress1&$top=5');
const data = await response.json();
expect(data.value).toBeInstanceOf(Array);
});
});
/api/data/v9.1/accounts → https://yourorg.crm4.dynamics.com/api/data/v9.1/accounts (adds auth)https://yourorg.crm4.dynamics.com/api/data/v9.1/accounts → same URL (adds auth)/api/data)az login)happy-dom)setupDataverse({
dataverseUrl: 'https://yourorg.crm4.dynamics.com', // Required
tokenRefreshInterval: 50 * 60 * 1000, // Optional: 50 minutes
enableConsoleLogging: true, // Optional: true
mockToken: 'mock-token-for-testing' // Optional: for testing
});
await setupDataverse() - see setup section abovehttps://yourorg.crm*.dynamics.comaz login to authenticate with Azure CLIIf you get Top-level 'await' expressions are only allowed when..., update your tsconfig.json:
{
"compilerOptions": {
"target": "es2022",
"module": "es2022"
}
}
This library requires a Node.js environment and has limited compatibility with browser-like test environments:
environment: "node" (default), environment: "jsdom"environment: "happy-dom"setupDataverse(options: DataverseSetupOptions): Promise<void>Setup dataverse testing utilities. Must be awaited.
options.dataverseUrl: Required HTTPS Dataverse URLoptions.tokenRefreshInterval: Optional token refresh interval (default: 50 minutes)options.enableConsoleLogging: Optional console logging (default: true)options.mockToken: Optional mock token for testingresetDataverseSetup(): voidReset the setup state (useful for testing the library itself).
getAzureToken(options: AzureCliOptions): string | nullGet Azure CLI access token for advanced use cases.
options.resourceUrl: Required Dataverse URLoptions.enableLogging: Optional logging (default: true)# Clone the repository
git clone <repository-url>
cd dataverse-utilities
# Install dependencies
npm install
# Build the project
npm run build
npm run build - Build the librarynpm run dev - Build in watch modenpm run test - Run testsnpm run test:watch - Run tests in watch modenpm run test:coverage - Run tests with coveragenpm run lint - Lint the codenpm run lint:fix - Fix linting errorsnpm run format - Format the codenpm run clean - Clean build artifactsTests are written using Vitest and located in the tests/ directory:
# Run all tests (unit + security tests)
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
# Run integration tests (requires Azure CLI login)
npm run test:integration
Integration tests are skipped by default to avoid requiring real Azure CLI authentication. To run them:
az loginnpm run test:integrationThese tests validate the library against real Dataverse environments and are useful for manual verification but not required for CI/CD.
This project uses Biome for linting and formatting:
# Check code quality
npm run lint
# Fix issues automatically
npm run lint:fix
# Format code
npm run format
dataverse-utilities)Currently minimal - add your own Dataverse utilities here as needed.
dataverse-utilities/vite)createDataverseConfig(options) - Complete Vite configuration with proxy and authenticationcreateDataverseConfigWithDefaults(url?, overrides?) - Configuration with environment variable supportcreateAuthPlugin(options) - Authentication plugin for token injectioncreateDataverseProxy(options) - Proxy configuration for API routingcreateAdvancedDataverseProxy(options) - Multi-pattern proxy configurationdataverse-utilities/testing)setupDataverse(options) - Configure testing environment with automatic Azure authenticationresetDataverseSetup() - Reset setup state (useful for testing the library itself)getAzureToken(options) - Get Azure CLI access token for advanced use casesclearTokenCache() - Clear cached authentication tokenshasCachedToken() - Check if valid cached token exists@azure/identitydataverse-utilities/
├── src/
│ ├── auth/ # Authentication utilities
│ │ └── azure-auth.ts # Azure Identity SDK integration
│ ├── testing/ # Testing utilities
│ │ ├── index.ts # Testing exports
│ │ └── setup.ts # Test environment setup
│ ├── vite/ # Vite plugin utilities
│ │ ├── index.ts # Vite exports
│ │ ├── auth-plugin.ts # Authentication plugin
│ │ ├── config.ts # Configuration helpers
│ │ └── proxy.ts # Proxy configuration
│ └── index.ts # Main entry point
├── tests/ # Test files
├── dist/ # Build output
├── package.json # Package configuration
├── tsconfig.json # TypeScript configuration
├── tsup.config.ts # Build configuration
├── vitest.config.ts # Test configuration
└── biome.json # Linting configuration
git checkout -b feature/new-featurenpm test && npm run lintgit commit -m 'Add new feature'git push origin feature/new-featureMIT License - see the LICENSE file for details.
See CHANGELOG.md for a list of changes.
FAQs
TypeScript utilities for Microsoft Dataverse with Vite development plugins and testing support
We found that dataverse-utilities demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.