#import script alias

26 messages · Page 1 of 1 (latest)

forest geode
#

I want to import @scripts/my-fun-script.js into a pages/index.astro, how do I make that work?

mint dawnBOT
#

Hi @forest geode. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

You can set up an import alias for @scripts by adding it to your tsconfig.json under compilerOptions.paths:

{
  "compilerOptions": {
    "paths": {
      "@scripts/*": ["./src/scripts/*"]
    }
  }
}

Then, in your src/pages/index.astro, you can import the script using the alias. Depending on your use case:

In the frontmatter (runs at build time, server-side):

---
import '@scripts/my-fun-script.js';
---

In a <script> tag (runs in the browser, client-side):

<script>
  import '@scripts/my-fun-script.js';
</script>

After updating tsconfig.json, the dev server will automatically restart and the alias will be available throughout your project. [Import Aliases]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@forest geode Kapa.ai is still learning and improving, please let me know how I did by reacting below.

forest geode
#

@mint dawn I expect this script to be used client side, where should it go?

mint dawnBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

For client-side execution, your script should go inside a <script> tag in your component template (not in the frontmatter). Here's how it looks in src/pages/index.astro:

---
// frontmatter (server/build time only)
---

<html>
  <body>
    <!-- your page content -->
    <script>
      import '@scripts/my-fun-script.js';
    </script>
  </body>
</html>

By default, Astro will process this <script> tag with bundling, TypeScript support, and deduplication — so it's the recommended approach for client-side scripts living inside src/. [Script processing]

A few things to keep in mind:

  • Do not put client-side code in the frontmatter (between ---). That code runs only at build time on the server, where browser APIs like document and window are not available. [document/window error]
  • The <script> tag is automatically treated as a JS module (type="module"), so ESM import syntax works out of the box. [Script processing]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@forest geode Kapa.ai is still learning and improving, please let me know how I did by reacting below.

forest geode
#

@mint dawn here's my index.astro page, the script is not firing. <html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Donnie Damato</title>
</head>
<body>
<script>
import '@scripts/infinite-scroll.js';
</script>
hello world
</body>
</html>

mint dawnBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Your code looks correct syntactically, so the issue is likely one of these common causes:

1. Check your tsconfig.json alias

Make sure you've added the @scripts alias as discussed earlier:

{
  "compilerOptions": {
    "paths": {
      "@scripts/*": ["./src/scripts/*"]
    }
  }
}

If this is missing, the import will fail silently or throw an error.

2. Check the browser console for errors

Open your browser's developer tools and look for any errors in the console — a failed import or a path resolution issue would show up there.

3. Bundled scripts only execute once

By default, Astro processes <script> tags as bundled module scripts, which are only ever executed once. If you're navigating between pages with view transitions enabled, the script won't re-run on subsequent navigations. [Script re-execution]

4. Verify the script file path

Make sure the file actually exists at src/scripts/infinite-scroll.js. A typo in the filename would prevent it from loading.

5. Check what the script does

If infinite-scroll.js relies on DOM elements being present, make sure those elements exist in the HTML when the script runs. Since the <script> tag is placed before hello world in the <body>, it may execute before the rest of the DOM is ready. Try moving the <script> tag to just before the closing </body> tag:

<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Donnie Damato</title>
  </head>
  <body>
    hello world
    <script>
      import '@scripts/infinite-scroll.js';
    </script>
  </body>
</html>
#

[Client-Side Scripts]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@forest geode Kapa.ai is still learning and improving, please let me know how I did by reacting below.

forest geode
#

Here's the tsconfig.json { "extends": "astro/tsconfigs/strict", "compilerOptions": { "strictNullChecks": true, "allowJs": true, "baseUrl": ".", "paths": { "@assets/*": [ "src/assets/*" ], "@components/*": [ "src/components/*" ], "@content/*": [ "src/content/*" ], "@layouts/*": [ "src/layouts/*" ], "@pages/*": [ "src/pages/*" ], "@scripts/*": [ "src/scripts/*" ] } } }

#

@mint dawn there are no errors, the tsconfig is correct, the only contents of that file are console.log(true) so it does not depend on the DOM

mint dawnBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Since the script only contains console.log(true) and there are no errors, the most likely culprit is script deduplication. By default, Astro processes <script> tags as bundled module scripts, which are only executed once per page load — and if you've navigated to the page before (e.g., via hot reload or view transitions), it may appear not to fire. [Script processing]

To confirm the script is actually running, try a hard refresh in your browser (Ctrl+Shift+R / Cmd+Shift+R) and check the console again.

If you want the script to run every time without Astro's bundling/deduplication, you can use is:inline to opt out of processing:

<script is:inline>
  import '@scripts/infinite-scroll.js';
</script>

⚠️ Note: is:inline disables Astro's script processing, which means import resolution won't work — so the @scripts alias won't be resolved. [Unprocessed scripts]

In that case, you'd need to inline the console.log(true) directly:

<script is:inline>
  console.log(true);
</script>

If you want to keep using the alias and bundling, stick with the processed <script> tag and verify with a hard refresh that the log appears in the browser console on first load.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@forest geode Kapa.ai is still learning and improving, please let me know how I did by reacting below.

forest geode
#

@mint dawn using is:inline shows: Uncaught SyntaxError: Cannot use import statement outside a module (at (index):4:13)

mint dawnBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

This error is expected and explained in the Astro docs. When you use is:inline, the <script> tag is no longer treated as a module, so import statements don't work inside it. [Cannot use import statement]

You have two options:

Option 1: Add type="module" alongside is:inline

<script type="module" is:inline>
  import '@scripts/infinite-scroll.js';
</script>

⚠️ However, note that is:inline disables Astro's import resolution, so the @scripts alias will not be resolved. This will likely cause another error.

Option 2: Inline the code directly (no import needed)

Since your script currently just contains console.log(true), write it directly:

<script is:inline>
  console.log(true);
</script>

That said, going back to the root issue — the processed <script> tag (without is:inline) is the correct approach for using the @scripts alias. If console.log(true) isn't appearing in the console with the standard processed script, please confirm:

  1. You're doing a hard refresh (Ctrl+Shift+R / Cmd+Shift+R) to rule out caching.
  2. You're checking the correct browser tab's console.

The processed script should work as-is for a simple console.log. [Script processing]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@forest geode Kapa.ai is still learning and improving, please let me know how I did by reacting below.

forest geode
#

@mint dawn type=module has this error Uncaught TypeError: Failed to resolve module specifier "@scripts/infinite-scroll.js". Relative references must start with either "/", "./", or "../".

mint dawnBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

This confirms the issue: is:inline disables Astro's import resolution, so the @scripts alias cannot be resolved by the browser — the browser has no knowledge of your tsconfig.json paths. [Unprocessed scripts]

The correct solution is to go back to the standard processed <script> tag (no is:inline, no extra attributes):

<script>
  import '@scripts/infinite-scroll.js';
</script>

Astro's script processing handles the alias resolution and bundling. The is:inline path was a dead end here.

Since you confirmed there are no errors with the processed script, the console.log(true) is likely running — it just runs once due to Astro's deduplication. Please do a hard refresh (Ctrl+Shift+R / Cmd+Shift+R) and check the console. If it logs true on that hard refresh, your setup is working correctly. [Script processing]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@forest geode Kapa.ai is still learning and improving, please let me know how I did by reacting below.