--- sourceDocument: Brazil Build or modify applications sourceDocumentLink: https://www.servicenow.com/docs/r/application-development Release : - brazil ft:locale : - en-US ft:publication_title : - Brazil Build or modify applications ft:clusterId : - cadev bundleId : - cadev workflow : - Development, Data, and Analytics --- # Create your first Lux experience # Create your first Lux experience {#ariaid-title1} Release version: Brazil Updated September 29, 2026 ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 minutes to read Install the ServiceNow SDK toolchain, scaffold a new Lux application, and deploy your first app to your ServiceNow instance. This foundational workflow guides you through environment setup, local development, and deployment. ## About this task If you'd rather use Lux Lab or the ServiceNow Lux Lab for VS Code extension, which wrap these same steps in a UI, see [Development tooling](https://www.servicenow.com/docs/Nd3S~fHELTzfg9bzn31~RQ "Three tools can build a Lux experience: Lux Lab, ServiceNow Lux Lab for VS Code, and the ServiceNow SDK. Lux and ServiceNow Lux Lab for VS Code build on the ServiceNow SDK foundation."). ## Before you begin * Role required: admin * Node.js 24 or later and `pnpm` 10 or later * A ServiceNow instance you can deploy to * `@servicenow/sdk` installed globally: `npm install -g @servicenow/sdk@latest` ## Procedure 1. Check your prerequisites Verify that you have the right version of Node.js. node --version Verify that you have the right version of pnpm. pnpm --version Verify that you have the right version of the ServiceNow SDK. now-sdk --version If your version does not match the listed requirements, install or update your packages as necessary. 2. Connect the ServiceNow SDK to your instance Run the following command to authenticate the now-sdk with your ServiceNow instance: now-sdk auth --add https://your-instance.service-now.com --type basic --alias dev Replace `your-instance` with your actual instance name. You will be prompted to enter your ServiceNow username and password. For more information on instance setup or other authentication methods, see the [ServiceNow SDK authentication documentation](https://www.servicenow.com/docs/r/application-development/servicenow-sdk/authenticate-instance-now-sdk.html). 3. Scaffold the application Run the following commands to create a local directory for your first experience and initialize a new ServiceNow application project. This scaffolds the project for Lux development with a boilerplate structure including configuration files, build scripts, and server-side logic. mkdir my-app && cd my-app npx @servicenow/sdk@latest init --template javascript.aiux You will see prompts for an app name, package name (also used as the URL basename), and scope name. To skip the prompts: npx @servicenow/sdk@latest init --template javascript.aiux --appName my-app --scopeName x_aix_myapp --packageName my-app The scope name must start with your vendor prefix and be 18 characters or fewer, including the prefix. Don't change it after the first install. Changing it without uninstalling the old scope from the instance creates a duplicate. Note: For more information about application scope naming, refer to: [Namespace identifier](https://www.servicenow.com/docs/r/application-development/c_NamespaceIdentifier.html). You can use the following options with `init`: {#create-your-first-experience__table-create-your-first-experience-flags__entry__2} | Flag | Purpose | |-|-| | `--appName` | Name of the application project | | `--packageName` | Package name for the project. Must follow npm naming conventions. | | `--scopeName` | Application scope name. Must start with your vendor prefix, be 18 characters or fewer including the prefix, and be unique on the instance. | | `--template` | Starter template for the project. Use `javascript.aiux` for a Lux application. | [ ] {#create-your-first-experience__table-create-your-first-experience-flags} The scaffold generates the following project structure. my-app/ ├── aiux.json # Lux app manifest --- app name, URL basename, landing route ├── now.config.json # ServiceNow scope manifest --- scope, scopeId, install settings ├── package.json # Depends on the Lux runtime + @servicenow/sdk ├── application.js # App-level lifecycle hooks (setup, navigate, teardown) ├── theme.js # App theme tokens (colors, radii) ├── tailwind.app.css # Tailwind configuration ├── head.app.css # App-level head styles ├── eslint.config.mjs # ESLint flat config ├── pages/ # File-based routing --- one directory per route │ ├── home/ │ │ ├── page.js # The page (default export) │ │ └── components/ # Components co-located with the page that uses them │ └── incidents/ │ └── page.js # A page with a static async loader(ctx) ├── widgets/ # Custom widgets (+ server scripts) │ └── aiux-hello-world/ │ ├── index.js │ └── server-script.js ├── scripts/ # Postinstall helpers ├── dist/ # Build output (generated --- do not commit) └── dist-metadata/ # Build metadata (generated --- do not commit) The scaffold's .gitignore already excludes dist/ and dist-metadata/, because the build generates both. 4. Install dependencies Run the following command to install dependencies. pnpm install 5. Run the example locally Use the following command to start a local dev server. pnpm run dev This spins up the full request pipeline on your machine with hot reload, so you can build against a real instance locally. To see your experience, open http://localhost/aiux/\/\ in your browser. Example: if your app's `basename` is `my-app` and you want to access the `/home` route: http://localhost/aiux/my-app/home Note: The path after /aiux/ is your app's basename (from aiux.json) followed by the page route: * /aiux/my-app/home = basename `my-app` + route `/home` * /aiux/my-app/dashboard = basename `my-app` + route `/dashboard` Editing a file under pages/ or components/ automatically recompiles and reloads the page in your browser. Build artifacts are written to .dev directories during development. You can try creating a page to add more to your experience: [Create a page](https://www.servicenow.com/docs/_evQSbH3TwJw0TF5_xzn4Q "Add a page to a Lux app. A page is a Lit web component that Lux registers as a route based on where you put its file."). 6. Build pnpm run build This compiles your pages and widgets into an installable package, written to dist/. It also confirms that the toolchain and dependencies are in place. A clean build means that Node, pnpm, and the project dependencies all resolved correctly. 7. Deploy Make sure you've run the build before you deploy. pnpm run deploy This installs the application on your ServiceNow instance. Open https://\/aiux/\ to see it live. ## Result The starter app ships two routes (Home and Incidents), an example component, and an example widget. ## What to do next * [Lux architecture](https://www.servicenow.com/docs/Y~e21ODPI9Ot_dY00HaoDQ "Lux renders UI as a separate service in front of a ServiceNow instance. It builds pages, sends HTML to the browser, and calls back for data.") for how these pieces fit together * [Create a page](https://www.servicenow.com/docs/_evQSbH3TwJw0TF5_xzn4Q "Add a page to a Lux app. A page is a Lit web component that Lux registers as a route based on where you put its file.") to add more routes * [Lux widgets](https://www.servicenow.com/docs/bh2byDjZNCxkuhdekwAn_w "A widget in Lux is a custom UI unit authored for a specific application. The platform ships no widgets; every widget on an instance was authored for an app.") to build the widget the scaffold generated