{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":1970,"path":"application-development/create-your-first-experience.md","title":"Create your first Lux experience","bundle":null,"doc_type":null,"release":"australia","body":"\n# Create your first Lux experience\n\nInstall 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.\n\n## About this task\n\nIf you'd rather use Lux Lab or the VS Code extension, which wrap these same steps in a UI, see [Development tooling](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/development-tooling.md).\n\n## Before you begin\n\n-   Role required: admin\n-   Node.js 24 or later and `pnpm` 10 or later\n-   A ServiceNow instance you can deploy to\n-   `@servicenow/sdk` installed globally: `npm install -g @servicenow/sdk@latest`\n\n## Procedure\n\n1.  Check your prerequisites\n\n    Verify that you have the right version of Node.js.\n\n    ```\n    node --version\n    ```\n\n    Verify that you have the right version of pnpm.\n\n    ```\n    pnpm --version\n    ```\n\n    Verify that you have the right version of the ServiceNow SDK.\n\n    ```\n    now-sdk --version\n    ```\n\n    If your version does not match the listed requirements, install or update your packages as necessary.\n\n2.  Connect the ServiceNow SDK to your instance\n\n    Run the following command to authenticate the now-sdk with your ServiceNow instance:\n\n    ```\n    now-sdk auth --add https://your-instance.service-now.com --type basic --alias dev\n    ```\n\n    Replace `your-instance` with your actual instance name. You will be prompted to enter your ServiceNow username and password.\n\n    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).\n\n3.  Scaffold the application\n\n    Run the following command 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.\n\n    ```\n    mkdir my-app && cd my-app\n    npx @servicenow/sdk@latest init --template javascript.aiux\n    ```\n\n    You will see prompts for an app name, package name \\(also used as the URL basename\\), and scope name. To skip the prompts:\n\n    ```\n    npx @servicenow/sdk@latest init --template javascript.aiux --appName my-app --scopeName x_aix_myapp --packageName my-app\n    ```\n\n    The scope name must start with your vendor prefix and be 18 characters or fewer. Don't change it after the first install. Changing it without uninstalling the old scope from the instance creates a duplicate.\n\n    **Note:** For more information about application scope naming, refer to: [application scope naming documentation](https://www.servicenow.com/docs/r/application-development/c_NamespaceIdentifier.html).\n\n    |Flag|Purpose|\n    |----|-------|\n    |`--instance=<url>`|ServiceNow instance URL|\n    |`--scope=<scope>`|App scope for scoped applications|\n    |`--template=<name>`|Starter template \\(default: default\\)|\n    |`--env`|Create .env file interactively|\n\n    The scaffold generates the following project structure.\n\n    ```\n    my-app/\n    ├── aiux.json              # Lux app manifest — app name, URL basename, landing route\n    ├── now.config.json        # ServiceNow scope manifest — scope, scopeId, install settings\n    ├── package.json           # Depends on the Lux runtime + @servicenow/sdk\n    ├── application.js         # App-level lifecycle hooks (setup, navigate, teardown)\n    ├── theme.js               # App theme tokens (colors, radii)\n    ├── tailwind.app.css       # Tailwind configuration\n    ├── head.app.css           # App-level head styles\n    ├── eslint.config.mjs      # ESLint flat config\n    ├── pages/                 # File-based routing — one directory per route\n    │   ├── home/\n    │   │   ├── page.js        # The page (default export)\n    │   │   └── components/    # Components co-located with the page that uses them\n    │   └── incidents/\n    │       └── page.js        # A page with a static async loader(ctx)\n    ├── widgets/               # Custom widgets (+ server scripts)\n    │   └── aiux-hello-world/\n    │       ├── index.js\n    │       └── server-script.js\n    ├── utils/                 # Shared utility modules\n    ├── scripts/               # Postinstall helpers\n    ├── dist/                  # Build output (generated — do not commit)\n    └── dist-metadata/         # Build metadata (generated — do not commit)\n    ```\n\n    Add `dist/` and `dist-metadata/` to your `.gitignore`. The build generates both.\n\n4.  Install dependencies\n\n    Run the following command to install dependencies.\n\n    ```\n    pnpm install\n    ```\n\n5.  Run the example locally\n\n    Use the following command to start at local dev server.\n\n    ```\n    pnpm run dev\n    ```\n\n    This spins up the full request pipeline on your machine with hot reload, so you can build against a real instance locally.\n\n    To see your experience, Open `http://localhost/aiux/<basename>/<route>` in your browser.\n\n    Example: if your app's `basename` is `my-app` and you want to access the `/home` route: `http://localhost/aiux/my-app/home`\n\n    **Note:** The path after `/aiux/` is your app's basename \\(from `aiux.json`\\) followed by the page route:\n\n    -   `/aiux/my-app/home` = basename `my-app` + route `/home`\n    -   `/aiux/my-app/dashboard` = basename `my-app` + route `/dashboard`\n    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.\n\n    You can try creating a page to add more to your experience: [Create a page](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/create-a-page.md).\n\n6.  Build\n\n    ```\n    pnpm run build\n    ```\n\n    This compiles your pages and widgets into an installable package, written to `dist/`. It also confirms that the toolchain and dependencies are in place.\n\n    A clean build means that Node, pnpm, and the @servicenow/karuna package all resolved correctly.\n\n7.  Deploy\n\n    ```\n    pnpm run deploy\n    ```\n\n    This installs the application on your ServiceNow instance. Open `https://<your-instance>/aiux/<basename>` to see it live.\n\n\n## Result\n\nThe starter app ships two routes \\(Home and Incidents\\), an example component, and an example widget.\n\n## What to do next\n\n-   [Lux architecture](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/lux-architecture.md) for how these pieces fit together\n-   [Create a page](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/create-a-page.md) to add more routes\n-   [Lux Widgets](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/widgets.md) to build the widget the scaffold generated\n\n"}}