Using the library in your widget

Oct 13, 2025 by wbrum.org 17 views

Introduction

When developing a widget, it's essential to consider the various components that make up the application. One crucial aspect is the ability to interact with external resources, such as libraries or modules, to enhance the functionality of the widget. In this article, we'll explore how to use external modules in widget development, focusing on the specific case of using the native-file-system-adapter library to save files to the local machine.

Understanding the native-file-system-adapter library

The native-file-system-adapter library is a powerful tool for interacting with the file system on the local machine. It provides a simple and intuitive API for saving files, making it an excellent choice for widget development. However, as you've encountered, using this library can be a bit more complex due to its modular structure.

The issue with the library's structure

The native-file-system-adapter library is not a single JavaScript file but rather a collection of smaller modules. This modular structure can make it challenging to use the library, especially when trying to import individual modules. In your case, you're trying to use the showSaveFilePicker.js module, which is part of the library.

The error: `Uncaught SyntaxError: export declarations may only appear at top level of a module`

When you try to add the showSaveFilePicker.js module as a resource, you encounter the error Uncaught SyntaxError: export declarations may only appear at top level of a module. This error occurs because the module is not being imported correctly.

Why is this happening?

The reason for this error is that the showSaveFilePicker.js module is not a standalone JavaScript file but rather a part of the larger native-file-system-adapter library. When you try to import it as a resource, the browser is trying to execute it as a separate module, which is causing the error.

How to fix the issue

To fix this issue, you need to import the native-file-system-adapter library as a whole, rather than trying to import individual modules. You can do this by adding the following script tag to your HTML file:

<script src="https://cdn.jsdelivr.net/npm/native-file-system-adapter@3.0.1/src/index.js"></script>

This will import the entire native-file-system-adapter library, making its modules available for use in your widget.

Using the library in your widget

Once you've imported the library, you can use its modules to interact with the file system. In your case, you can use the showSaveFilePicker function to save files to the local machine. Here's an example of how you can use it:

import { showSaveFilePicker } from 'native-file-system-adapter';

// Call the showSaveFilePicker function to save a file
showSaveFilePicker({
  types: [
    {
      description: 'CSV file',
      accept: {
        'text/csv': ['.csv'],
      },
    },
  ],
}).then((fileHandle) => {
  // Get the file's contents
  const file = await fileHandle.getFile();
  const contents = await file.text();

  // Do something with the file's contents
  console.log(contents);
});

In this example, we're using the showSaveFilePicker function to save a CSV file to the local machine. We're passing an options object to the function, which specifies the type of file we want to save (in this case, a CSV file). We're then using the getFile method to get the file's contents and logging it to the console.

Conclusion

Using external modules in widget development can be a bit complex, but with the right approach, it can be a powerful tool for enhancing the functionality of your widget. In this article, we've explored how to use the native-file-system-adapter library to save files to the local machine. By importing the library as a whole and using its modules correctly, you can create a robust and feature-rich widget that meets the needs of your users.

Additional resources

native-file-system-adapter library documentation
CDN link for native-file-system-adapter library
Widget development best practices
Q&A: Using External Modules in Widget Development =====================================================

Introduction

In our previous article, we explored how to use the native-file-system-adapter library to save files to the local machine in widget development. However, we know that there are many more questions and concerns when it comes to using external modules in widget development. In this article, we'll answer some of the most frequently asked questions about using external modules in widget development.

Q: What are external modules, and why do I need them?

A: External modules are pre-written code libraries that can be used in your widget to perform specific tasks. They can be used to enhance the functionality of your widget, make it more efficient, and provide a better user experience. External modules can be used for a wide range of tasks, such as interacting with the file system, making API calls, or performing complex calculations.

Q: How do I add external modules to my widget?

A: To add an external module to your widget, you need to import it into your code. This can be done using a script tag in your HTML file or by importing the module using a JavaScript import statement. For example, if you want to use the native-file-system-adapter library, you can add the following script tag to your HTML file:

<script src="https://cdn.jsdelivr.net/npm/native-file-system-adapter@3.0.1/src/index.js"></script>

Q: What is the difference between a script tag and a JavaScript import statement?

A: A script tag is used to add a JavaScript file to your HTML file, while a JavaScript import statement is used to import a module into your code. Script tags are typically used for adding external libraries or frameworks, while JavaScript import statements are used for importing specific modules or functions.

Q: How do I use the imported module in my code?

A: Once you've imported the module, you can use its functions or variables in your code. For example, if you've imported the native-file-system-adapter library, you can use the showSaveFilePicker function to save a file to the local machine:

import { showSaveFilePicker } from 'native-file-system-adapter';

// Call the showSaveFilePicker function to save a file
showSaveFilePicker({
  types: [
    {
      description: 'CSV file',
      accept: {
        'text/csv': ['.csv'],
      },
    },
  ],
}).then((fileHandle) => {
  // Get the file's contents
  const file = await fileHandle.getFile();
  const contents = await file.text();

  // Do something with the file's contents
  console.log(contents);
});

Q: What are some common issues I might encounter when using external modules?

A: Some common issues you might encounter when using external modules include:

Import errors: Make sure you've imported the module correctly and that the module is available in your code.
Function not found: Make sure you're using the correct function or variable from the module.
Module not loaded: Make sure the module has been loaded correctly and that it's available in your code.

Q: How do I troubleshoot issues with external modules?

A: To troubleshoot issues with external modules, follow these steps:

Check the console: Look for any error messages in the console that might indicate the issue.
Verify the import: Make sure you've imported the module correctly and that it's available in your code.
Check the module documentation: Look for documentation on the module's functions and variables to ensure you're using them correctly.
Reach out to the community: If you're still having trouble, reach out to the community for help and support.

Conclusion

Using external modules in widget development can be a powerful tool for enhancing the functionality of your widget. By understanding how to add, use, and troubleshoot external modules, you can create a robust and feature-rich widget that meets the needs of your users. Remember to always check the console, verify the import, and check the module documentation to troubleshoot any issues you might encounter.