1# Node.js Entry Point (REQUIRED)
2 
3Azure Functions Node.js v4 programming model requires an entry point file that initializes the runtime.
4 
5> ⛔ **CRITICAL**: Without this file, functions will deploy but return 404 on all endpoints.
6 
7## Project Structure (CRITICAL)
8 
9The project structure MUST be:
10 
11```
12project-root/                # ← azure.yaml project: "."
13├── azure.yaml
14├── package.json             # ← MUST be at ROOT, not in src/
15├── host.json
16├── src/
17│   ├── index.js             # ← Entry point (app.setup)
18│   └── functions/
19│       ├── myFunction.js    # ← Functions auto-discovered
20│       └── ...
21└── infra/
22```
23 
24> ⛔ **CRITICAL**: `package.json` MUST be at project root, NOT inside `src/`.
25> The `azure.yaml` must have `project: .` (not `project: ./src/`).
26 
27## JavaScript: src/index.js
28 
29**This file MUST exist and MUST NOT be removed when replacing trigger files.**
30 
31```javascript
32const { app } = require('@azure/functions');
33 
34app.setup({
35    enableHttpStream: true,
36});
37```
38 
39## TypeScript: src/index.ts
40 
41**This file MUST exist and MUST NOT be removed when replacing trigger files.**
42 
43```typescript
44import { app } from '@azure/functions';
45 
46app.setup({
47    enableHttpStream: true,
48});
49```
50 
51## package.json Configuration
52 
53The `package.json` MUST be at the project root (same level as `azure.yaml`).
54 
55> ⛔ **CRITICAL: The glob pattern is REQUIRED for function discovery!**
56> Using `"main": "src/index.js"` alone will result in 404 on all endpoints.
57> You MUST use the glob pattern that includes function files.
58 
59### JavaScript (REQUIRED pattern)
60```json
61{
62  "main": "src/{index.js,functions/*.js}",
63  "scripts": {
64    "start": "func start"
65  }
66}
67```
68 
69### TypeScript (REQUIRED pattern)
70```json
71{
72  "main": "dist/src/{index.js,functions/*.js}",
73  "scripts": {
74    "build": "tsc",
75    "prestart": "npm run build",
76    "start": "func start"
77  }
78}
79```
80 
81> **Why the Glob Pattern is Required**: The Azure Functions Node.js v4 runtime uses the `main` field to determine which files to load. Unlike CommonJS where `require()` chains work, the runtime needs ALL function files explicitly listed in the glob pattern. Without the glob, only `index.js` loads and functions in `src/functions/` are never registered.
82>
83> ❌ **WRONG**: `"main": "src/index.js"` — Functions not discovered, 404 on all routes
84> ✅ **CORRECT**: `"main": "src/{index.js,functions/*.js}"` — All functions discovered
85 
86## azure.yaml Configuration
87 
88```yaml
89services:
90  api:
91    project: .           # ← ROOT directory, not ./src/
92    language: js         # or ts for TypeScript
93    host: function
94```
95 
96> ⛔ **CRITICAL**: Use `project: .` — NOT `project: ./src/`. The runtime expects `package.json` at the project root.
97 
98## Build Requirements (TypeScript only)
99 
100Before deployment, TypeScript must be compiled:
101 
102```bash
103npm run build
104```
105 
106This outputs JavaScript to `dist/` which is what Azure Functions actually runs.
107 
108## Common Mistakes
109 
110| Mistake | Symptom | Fix |
111|---------|---------|-----|
112| **Using `"main": "src/index.js"` without glob** | **404 on all endpoints** | **Use `"main": "src/{index.js,functions/*.js}"`** |
113| Missing `src/index.js` | 404 on all endpoints | Add the entry point file with `app.setup()` |
114| Deleting `src/index.js` when replacing triggers | 404 after recipe applied | Keep index.js, only replace function files |
115| `package.json` in `src/` instead of root | 404, functions not found | Move `package.json` to project root |
116| `project: ./src/` in azure.yaml | Deployment fails or 404 | Use `project: .` |
117| Missing `npm run build` for TypeScript | 404 or old code runs | Run build before deploy |
118 
119> ⛔ **#1 CAUSE OF 404 ERRORS**: Using `"main": "src/index.js"` instead of the glob pattern.
120> The glob `src/{index.js,functions/*.js}` is **REQUIRED** — it's not optional!
121 
122## Terraform vs Bicep: Source Code is IDENTICAL
123 
124The Node.js source code and `package.json` are **exactly the same** for both IaC types.
125 
126Only the `infra/` folder differs:
127- Bicep: `infra/*.bicep`
128- Terraform: `infra/*.tf`
129 
130> ⚠️ If you find yourself changing imports or source code because of IaC choice, something is wrong. The application code should be IaC-agnostic.
131