Kickstart Angular

Kickstart Angular is a pre-built starter for connecting Angular applications to Contentstack. The repository uses Angular 21 with standalone components and the application builder. Use this starter to set up a Contentstack-powered app with the following preconfigured features:

• Contentstack SDK: Provides tools for content retrieval.
• Live Preview: Enables real-time content visualization within the app.
• Visual Builder: Supports on-page content editing.

By the end of this guide, you will be able to:

• Provision a stack and sample content by importing the Angular Starter
• Optionally deploy the app with Launch and reuse the environment configuration
• Use the Contentstack Delivery SDK to fetch content in an Angular application
• Configure Live Preview and Visual Editor for real-time content updates and inline editing
• Fetch and render Contentstack content in Angular components
• Work with Angular standalone components, signals, and the inject() function used in the Kickstart
• Generate Angular environment files from a .env file using the generate-env.js script
• Connect the local app using delivery and preview tokens (from the stack or mapped from Launch)

Before you begin, ensure you have the following:

• Node.js (v19 or higher) installed on your machine
• Basic understanding of JavaScript and/or TypeScript
• A Contentstack account
• Organization Owner/Admin access to import a Starter, which creates a new stack.
• A GitHub account to deploy using Launch or clone the fork

Note Kickstart projects use a shared content model. Reuse one stack across projects, or create separate stacks for isolated content and configuration.

Use the following guides to complete setup:

• Importing a Starter: Import a prebuilt stack and content model.
• Launch Quick Start Guide with Angular: Connect GitHub, deploy the app, configure environment variables, and manage deployments.

Outcome:

• A stack with sample content
• A hosted application
• A GitHub repository (if Deploy in Launch is used)

For local development, clone the repository and install dependencies:

• If you used Launch, clone the repository linked to your deployment (from Launch or GitHub).
• If not, clone the official repository.

git clone https://github.com/contentstack/kickstart-angular.git
cd kickstart-angular

In the cloned project folder, run:

npm install

This installs the project dependencies so you can run and build the app locally.

The Angular Kickstart uses a predefined stack seed available in the contentstack/kickstart-stack-seed repository. Import this seed into your stack using the Contentstack CLI equivalent to a Starter import.

This approach is useful for terminal-first workflows, repeatable setups (e.g., onboarding or CI), or teams that standardize on the CLI.

Note If you already have a stack created from this seed (or another Kickstart), you can use that stack instead and skip this step.

1. Install the Contentstack CLI (if needed):
   1

   npm install -g @contentstack/cli

2. If you are setting up the CLI for the first time, set your region:
   1

   csdx config:set:region EU

Note Free developer stacks typically use the EU region.

3. Sign in using the following command and provide your Contentstack account details when prompted:
   1

   csdx auth:login

4. Get your Organization ID from the Contentstack dashboard. For detailed steps, refer to the Organization Information document.
5. Create a stack:
   1. Seed from the repository
      1

      csdx cm:stacks:seed --repo "contentstack/kickstart-stack-seed" --org "<ORG_ID>" -n "CS Kickstart Angular"

   2. Interactive bootstrap

      For a quick local setup, run:

      1

      csdx cm:bootstrap

After the process completes, the CLI:

• Creates a new Contentstack stack (e.g., CS Kickstart Angular)
• Imports Angular Kickstart content models
• Adds sample entries

Gather these before updating .env. Use the stack you created with the Starter or CLI commands earlier. Create a new stack manually only if you are not using any of those paths.

1. Log in to Contentstack and open your stack.
2. Navigate to Settings > Tokens and create a new Delivery Token.
3. Ensure the Preview Token is enabled (it is enabled by default).
4. In the environment settings, set the URL to http://localhost:4200/.

After you have a stack and a local clone, follow the instructions to connect the app to Contentstack.

1. Rename .env.example to .env in the project root. Alternatively, create the .env file with the same variables.
2. Add your Contentstack credentials:

NG_APP_CONTENTSTACK_API_KEY=<STACK_API_KEY>
NG_APP_CONTENTSTACK_DELIVERY_TOKEN=<DELIVERY_TOKEN>
NG_APP_CONTENTSTACK_PREVIEW_TOKEN=<PREVIEW_TOKEN>
NG_APP_CONTENTSTACK_ENVIRONMENT=preview
NG_APP_CONTENTSTACK_REGION=EU
NG_APP_CONTENTSTACK_PREVIEW=true

Note Live Preview is enabled by default for this feature.

Credential details

• API Key: From your stack (e.g., Settings > API Keys).
• Delivery Token / Preview Token: From the token created (with Preview enabled) or the same logical values from Launch after you map them to NG_APP_* keys.
• Environment: The publishing environment for preview (e.g., preview or development).
• Region: Stack region (e.g., NA, EU, AZURE-NA).
• Preview: Set true to enable Live Preview in the app.

Note Free Contentstack developer accounts are bound to the EU region. The CDN automatically routes API requests to keep them responsive.

The project uses the generate-env.js script to convert .env values into Angular environment files.

The script:

• Runs automatically before npm run start and npm run build via prestart and prebuild in package.json
• Reads from .env if present; otherwise from process.env, using only NG_APP_CONTENTSTACK_* variables.
• Generates:
  • src/environments/environment.ts
  • src/environments/environment.production.ts

These files contain the Contentstack configuration and API endpoints used by the app.

You can override the default endpoints with the following variables:

• NG_APP_CONTENTSTACK_CONTENT_DELIVERY
• NG_APP_CONTENTSTACK_PREVIEW_HOST
• NG_APP_CONTENTSTACK_CONTENT_APPLICATION

If omitted, the contentstack-endpoints package resolves the endpoints from your region.

Warning Do not commit the .env file to version control. It is listed in .gitignore.

1. In your Contentstack stack, navigate to Live Preview from the Settings menu.
2. Select the Enable Live Preview checkbox.
3. Select the environment that matches your app (e.g., if NG_APP_CONTENTSTACK_ENVIRONMENT=preview, choose Preview).
4. Click Save.

Contentstack then sends Live Preview updates to your app. Run the app and confirm content loads in the Verify Your Setup section.

Run the app and confirm it loads content from your stack.

1. Run the following command:

npm run start

This runs the npm prestart script (node generate-env.js), then ng serve. That regenerates the Angular environment files from .env.

You should see the homepage with:

• A title, description, and image from your stack
• Example modular blocks

If the page is empty or shows an error, check:

• The stack was provisioned with the Angular Starter (or equivalent seed). See Importing a Starter
• Delivery token and environment in .env are correct
• Environment files are up to date. Run npm run start again if needed.

NoteUse an LTS version of Node.js (e.g., v20). Odd-numbered versions (e.g., v21) are not LTS but still work.

Prerequisites:

• Live Preview enabled in the stack
• NG_APP_CONTENTSTACK_PREVIEW=true in .env

Steps:

1. Edit an entry in Contentstack (e.g., the homepage).
2. The app updates in the browser without a full reload.

Tip Open the entry in the CMS, then use the Live Preview icon or open Visual Editor so the app runs inside the CMS for click-to-edit.

Once dependencies are installed, your project has the following structure:

kickstart-angular/
├── src/
│   ├── app/
│   │   ├── app.component.ts
│   │   ├── components/
│   │   │   └── home/
│   │   │       ├── home.component.html
│   │   │       └── home.component.ts
│   │   └── services/
│   │       └── contentstack.service.ts
│   ├── environments/
│   │   ├── environment.production.ts
│   │   └── environment.ts
│   ├── global_styles.css
│   ├── index.html
│   ├── main.ts
│   └── vite-env.d.ts
├── .env.example
├── angular.json
├── generate-env.js
├── package.json
└── types.ts

• Angular workspace project: The angular.json file defines the application project name as demo under the projects.demo key.
• Build output: Running npm run build generates the output in the dist/demo directory. You can verify this path in angular.json under projects.demo.architect.build.options.outputPath.
• Package name: The package.json file defines the npm package name as kickstart-angular. This name differs from the Angular CLI project key.

• Entry: src/main.ts — bootstraps the app and routing
• Shell: src/index.html
• Global styles: src/global_styles.css (Tailwind)

Use the links below to view the current source on GitHub.

• File: src/app/services/contentstack.service.ts
• Initializes the Delivery SDK and optionally Live Preview
• Exposes getEntryByUrl() to load an entry by content type and URL
• Adds editable tags in preview mode so Visual Builder can bind CMS fields to the DOM

• File: src/app/components/home/home.component.ts
• Loads the page entry (/) and subscribes to ContentstackLivePreview.onEntryChange() to refetch on CMS updates.
• Uses Angular signals and inject() for page data

• File: src/app/components/home/home.component.html
• Renders page content and modular blocks with layout, image, title, and copy.
• Uses @if, @for, and data-cslp for Visual Builder

• File: generate-env.js
• Reads .env or process.env (NG_APP_CONTENTSTACK_*)
• Generates Angular environment files
• Runs before start and build

Optional overrides:

• NG_APP_CONTENTSTACK_CONTENT_DELIVERY
• NG_APP_CONTENTSTACK_PREVIEW_HOST
• NG_APP_CONTENTSTACK_CONTENT_APPLICATION

• Files: src/app/app.component.ts, src/main.ts
• Root shell with <router-outlet>
• Single route (/) mapped to Home

• Wrong Contentstack region
  • Free developer accounts are bound to the EU region. Setting NG_APP_CONTENTSTACK_REGION=NA (or another region) causes API calls to fail and content not to load.
  • Use NG_APP_CONTENTSTACK_REGION=EU in .env and when configuring the CLI (e.g., csdx config:set:region EU).
• Stack not seeded

  The application requires the page content type and sample entries to function correctly. You can provide this data by any one of the following methods:

  • Import the Angular Starter: Use the provided starter package to create the content model.
  • Seed via CLI: Run the csdx cm:stacks:seed command with the contentstack/kickstart-stack-seed repository.
  • Manual Configuration: Create a matching content model and entries that align with the application's data requirements.

  Note If the stack lacks a matching content model or entries, the application fails to fetch data for the home route (/). This results in an empty homepage or a 404 error.

• .env.example not renamed to .env
  The project reads configuration from .env. If you do not rename (or copy) .env.example to .env and add your credentials, the environment generation script has no values to use, and the SDK configuration fails.
• Wrong Live Preview URL
  Angular runs on http://localhost:4200/ by default. Configuring http://localhost:3000/ in your stack’s token or Live Preview settings breaks Live Preview and Visual Builder, even if the rest of the app loads.
• The environment generation script has not run
  Use npm run start, not ng serve directly. The prestart script runs generate-env.js and generates the Angular environment files from .env. Running ng serve skips this step, and the app uses a stale or empty configuration.
• Live Preview is not enabled in Stack Settings
  In your stack, go to Settings → Live Preview, enable it, and select the environment that matches your app (e.g., Preview). Otherwise, Live Preview updates are not injected.

• Committing .env
  The file contains API keys and tokens. Do not commit it; the repo already includes .env in .gitignore.
• Wrong or mismatched delivery/preview tokens
  Use the tokens from the token you created in the stack. Wrong or swapped tokens cause API or authentication failures.
• Incorrect publishing environment name
  The value of NG_APP_CONTENTSTACK_ENVIRONMENT (e.g., preview) must match an environment that exists in your stack.
• Empty or missing environment variables
  Ensure all required NG_APP_CONTENTSTACK_* variables in .env are set. Otherwise, the generated environment files contain empty values, and the SDK fails.
• Skipping npm install
  Run npm install after cloning so dependencies and the environment generation script can run.
• Removing or modifying generate-env.js
  The prestart and prebuild scripts depend on it. Changing or deleting it breaks environment file generation.
• Querying content not published to the configured environment
  The app fetches entries from the environment set in .env. Unpublished content or content in another environment will not appear.
• Wrong content type or URL in getEntryByUrl()
  The kickstart queries the page content type for the URL '/'. If you extend the app, the content type and url field must match what exists in your stack.

• Use Live Preview for CSR for simplicity with inline editing (good for getting started or when SEO is not critical).
• Use Angular Signals for a reactive state that works with Contentstack Live Preview.
• Use Standalone Components for an NgModule-free structure.
• Use Dependency Injection via inject() for services.

You can extend this kickstart with more routes and pages, or add server-side rendering with Angular Universal. The same ideas (SDK init, fetching by URL, Live Preview, and Visual Builder) apply across frameworks.

For questions or issues, join the Contentstack Community on Discord.