Skip to main content

The .cdk folder

.cdk/ is a folder beside project.yaml. The CDK reads it for the data a deck renders against, and for the replies it sends a fieldset in place of the network. The build ignores the folder, so nothing in it reaches an uploaded DeckVersion.

.cdk/
├── contexts/
│ ├── peak-season.json
│ └── first-year.json
├── feeds/
│ └── depot_list/
│ ├── peak-season.json
│ └── one-depot.json
├── envs/
│ ├── appointment/
│ ├── tenancy/
│ │ └── peak-season.json
│ └── user/
│ ├── peak-season.json
│ └── new-starter.json
├── customers/
│ ├── harbour-couriers/
│ │ ├── index.json
│ │ └── contacts/
│ │ ├── 91.json
│ │ └── 92.json
│ └── city-bike-share/
│ └── index.json
├── cmsvals/
│ └── peak-season.json
└── intercepts/
├── depots.js
└── bookings.js

Commit the folder. A fixture that stays on one machine reproduces a bug for one developer, and an intercept is deck code like any other.

Contexts​

A context is the set of values one preso carries. The app writes them when a salesperson personalises that preso. A deck reads them through Bridge.Context, or useSlideContext() in React.

One file is the whole context.

.cdk/contexts/peak-season.json
{
"hire": {
"depots": ["Harbour", "Rail Yard"],
"starts_on": "2027-12-18",
"days": 21,
"bikes": 40
}
}

Apply one under Contexts on the Fixtures page. The CDK stores what you type apart from the file, so switching fixture keeps your edits and drops the previous file's values. Empty applies no file.

Feeds​

One file per feed, under a folder named for the feed key:

.cdk/feeds/<feed-key>/<name>.json

The CDK shows a fixture list for each feed project.yaml declares. If the project file does not name the feed, the CDK ignores its folder.

A file contains the payload as the deck receives it. Bridge.Feed.get("depot_list") returns exactly what the file contains:

.cdk/feeds/depot_list/peak-season.json
{
"results": [
{ "id": 4, "name": "Harbour", "bikes": 18 },
{ "id": 9, "name": "Rail Yard", "bikes": 4 }
]
}

A saved response often covers several feeds at once. feed add splits it into one file per top-level key:

livepreso-cdk feed add ./downloaded-feeds.json --name peak-season

Add --force to overwrite files already there, and --dry-run to print the writes instead of making them.

Envs​

An env is a record the app hands a deck about who is presenting, and when. A deck reads envs through Bridge.Envs.

The CDK reads three folders, one per group:

FolderGroupFields
.cdk/envs/user/userid, first_name, last_name, email, profile
.cdk/envs/appointment/appointmentid, begin, end
.cdk/envs/tenancy/tenancyid, name, brand colour, logos

The CDK merges a file over the group's default, so a file needs only the fields it changes:

.cdk/envs/user/peak-season.json
{
"first_name": "Rosalind",
"last_name": "Okonkwo",
"profile": {
"position": "Fleet Consultant",
"mobile": "0400 000 111"
}
}

Apply one under Envs on the Fixtures page. Default applies no file, and the group stays as the CDK builds it.

The customer and contacts groups come from a customer fixture instead, and server comes from the API client.

Customers​

A customer fixture is the customer a preso is for, with the contacts attending it. A deck reads both through Bridge.Envs.

.cdk/customers/<key>/index.json
.cdk/customers/<key>/contacts/<id>.json

index.json is the customer record. title is the name the pickers show:

.cdk/customers/harbour-couriers/index.json
{
"id": 42,
"title": "Harbour Couriers",
"primary_colour": "2f6f4e",
"logo_original": null,
"profile": {
"fleet_size": 24,
"contract_ends": "2027-06-30"
}
}

Each contact gets a file, named for the id inside it:

.cdk/customers/harbour-couriers/contacts/91.json
{
"id": 91,
"email": "dd@example.com",
"name_first": "Dimitri",
"name_last": "Dubois",
"phone": null,
"profile": null
}

Write a contact the way the server sends one, with name_first and name_last. The CDK renames those two fields, so a deck reads first_name and last_name.

Apply a customer under Customer on the Fixtures page, then tick the contacts attending. The Hooks page keeps a separate selection on its bar. One search box there finds both: type a customer name or a contact name. Picking a contact also applies the customer they belong to.

CMS values​

A CMS val set is the company-wide values a deck starts from, as PresoManager would have stored them. One file is a list of rows:

.cdk/cmsvals/peak-season.json
[
{ "key": "hire-intro-heading", "value": "<h2>Your fleet, on tap</h2>", "mime": "text/plain" },
{ "key": "hire-intro-photo", "value": "https://example.com/depot.png", "mime": "image" }
]

Apply one under CMS Vals on the Fixtures page. The CDK stores what you type apart from the file, as it does for a context.

One name, every kind​

Give the files of one scenario the same name across kinds:

.cdk/contexts/peak-season.json
.cdk/feeds/depot_list/peak-season.json
.cdk/envs/user/peak-season.json
.cdk/cmsvals/peak-season.json

Anything that takes a fixture name then applies the whole set at once, and leaves a kind without a file of that name empty. The CLI takes one with --fixtures peak-season, and an AI tool over MCP applies one with set_fixtures and lists what a deck has with list_fixtures.

A customer is never part of a set. You pick one on the Fixtures page.

Intercepts​

An intercept catches a request a fieldset would send to the server, and answers it from a file. On the Hooks page you choose which reply each intercept sends, so you can try a form against a missing result, a 404 or a slow server. The deck needs no change for this, and cannot tell the difference.

A file is an ES module. Its default export is one intercept, or an array of them:

.cdk/intercepts/depots.js
export default {
name: "Depot search",
url: "**/api/bikehire/depots/**",
responses: [
{
label: "Two depots",
fulfill: () => ({
body: {
results: [
{ id: 4, name: "Harbour" },
{ id: 9, name: "Rail Yard" },
],
},
}),
},
{
label: "None",
fulfill: () => ({
body: { results: [] },
}),
},
{
label: "Not found",
fulfill: () => ({
status: 404,
}),
},
{
label: "Slow",
fulfill: () => ({
delay: 3000,
body: { results: [] },
}),
},
],
};
FieldRequiredMeaning
urlyesWhich requests this intercept answers. Three forms, below.
responsesyesThe replies you can choose between, each with a label and a fulfill. The first is the one an intercept starts on, so write the ordinary reply first.
namenoWhat the picker shows. Defaults to the filename, numbered when a file exports several intercepts.
methodnoAnswers this method alone, written in capitals: "POST". Any method matches when it is left out.

Matching a request​

A url takes one of three forms.

The CDK matches a glob string against the whole URL. ** spans separators, and * stops at one. A path on its own needs a leading **/ to clear the scheme and the host:

url:  "**/api/bikehire/depots/**"
GET https://example.com/api/bikehire/depots/?page=2 answered
GET https://example.com/api/bikehire/depots no match, the trailing ** needs a "/" before it

The CDK tests a RegExp against the whole URL. Use one when the part that identifies the request is in the query:

export default {
name: "Weather proxy",
url: /proxy.*source=bom/,
responses: [
{
label: "Fine",
fulfill: () => ({
body: { forecast: "fine" },
}),
},
],
};

A function receives the URL and the whole request, and returns whether it matches:

function isSecondPageOfDepots(url, request) {
return url.includes("/depots/") && Number(request.query.page) === 2;
}

export default {
name: "Depot page two",
url: isSecondPageOfDepots,
responses: [
{
label: "Empty page",
fulfill: () => ({
body: { results: [] },
}),
},
],
};

The first intercept that matches a request answers it. The CDK reads files in filename order, and reads the intercepts in a file in the order the file lists them.

Writing a response​

fulfill receives the request as { method, url, query, headers, body }. What it returns is what the deck gets:

ReturnedWhat the deck gets
{ body }A 200 carrying that body.
{ status }That status. 400 and above rejects the way superagent does, so the deck's catch runs.
{ delay }The same reply, after that many milliseconds.
nothingThe request goes to the real network.

An intercept that reads the request can answer a search the way the server would:

const depots = [
{ id: 4, name: "Harbour" },
{ id: 9, name: "Rail Yard" },
{ id: 12, name: "Airport" },
];

function findDepots(search) {
if (!search) {
return depots;
}

return depots.filter((depot) => depot.name.toLowerCase().includes(search.toLowerCase()));
}

export default {
name: "Depot search",
url: "**/api/bikehire/depots/**",
responses: [
{
label: "Matches the search",
fulfill: ({ query }) => ({
body: { results: findDepots(query.search) },
}),
},
],
};

A response that returns nothing sends the request on, so one endpoint can reach the server while the others stay mocked:

export default {
name: "Depot search",
url: "**/api/bikehire/depots/**",
responses: [
{
label: "Mocked",
fulfill: () => ({
body: { results: [] },
}),
},
{
label: "Ask the server",
fulfill: () => null,
},
],
};

Several in one file​

A list and a single record come back in different shapes, so one resource read both ways needs an intercept for each:

.cdk/intercepts/depots.js
export default [
{
name: "Depot detail",
url: "**/api/bikehire/depots/*/",
responses: [
{
label: "Harbour",
fulfill: () => ({
body: { id: 4, name: "Harbour" },
}),
},
],
},
{
name: "Depot list",
url: "**/api/bikehire/depots/**",
responses: [
{
label: "Two depots",
fulfill: () => ({
body: {
results: [
{ id: 4, name: "Harbour" },
{ id: 9, name: "Rail Yard" },
],
},
}),
},
],
},
];

The detail pattern goes first, because the first match answers and depots/** matches a detail URL too:

GET /api/bikehire/depots/4/      Depot detail
GET /api/bikehire/depots/?page=2 Depot list

Name every intercept. An intercept without a name takes the filename, and the number of intercepts in the file decides the rest:

depots.js exports one, unnamed    depots
depots.js exports two, unnamed depots 1, depots 2

The CDK remembers a picked response against the name, so adding that second intercept drops the response picked against depots.