{"id":8994,"library":"flask-assets","title":"Flask-Assets","description":"Flask-Assets (current version 2.1.0) provides asset management for Flask applications, integrating the `webassets` library to efficiently merge, minify, and compile CSS and JavaScript files. It simplifies frontend workflow by handling static resource optimization, with new versions released periodically to maintain compatibility with Flask and other dependencies.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"http://github.com/miracle2k/flask-assets","tags":["flask","assets","frontend","css","javascript","minification","bundling","webassets","jinja2"],"install":[{"cmd":"pip install Flask-Assets","lang":"bash","label":"Basic Installation"},{"cmd":"pip install Flask-Assets jsmin cssmin lesscpy pyscss","lang":"bash","label":"With Common Filters (JS/CSS Minification, LESS/SCSS Compilation)"}],"dependencies":[{"reason":"Core web framework integration.","package":"Flask"},{"reason":"The underlying asset management library Flask-Assets integrates with.","package":"webassets","optional":false},{"reason":"Optional filter for JavaScript minification.","package":"jsmin","optional":true},{"reason":"Optional filter for CSS minification.","package":"cssmin","optional":true},{"reason":"Optional filter for LESS compilation.","package":"lesscpy","optional":true},{"reason":"Optional filter for SCSS compilation.","package":"pyscss","optional":true}],"imports":[{"note":"Used to initialize the asset management environment.","symbol":"Environment","correct":"from flask_assets import Environment"},{"note":"Used to define collections of source files, filters, and output targets.","symbol":"Bundle","correct":"from flask_assets import Bundle"}],"quickstart":{"code":"from flask import Flask, render_template\nfrom flask_assets import Environment, Bundle\nimport os\n\napp = Flask(__name__)\n\n# Configure Flask for assets\napp.config['ASSETS_DEBUG'] = True # Set to False in production\n\n# Initialize Flask-Assets\nassets = Environment(app)\n\n# Define asset bundles\njs_bundle = Bundle(\n 'js/main.js',\n 'js/utils.js',\n filters='jsmin',\n output='gen/packed.js'\n)\ncss_bundle = Bundle(\n 'css/style.css',\n 'css/theme.css',\n filters='cssmin',\n output='gen/packed.css'\n)\n\n# Register bundles\nassets.register('main_js', js_bundle)\nassets.register('main_css', css_bundle)\n\n@app.route('/')\ndef index():\n return render_template('index.html')\n\nif __name__ == '__main__':\n # Create static/js and static/css directories for the example\n os.makedirs(os.path.join(app.static_folder, 'js'), exist_ok=True)\n os.makedirs(os.path.join(app.static_folder, 'css'), exist_ok=True)\n \n # Create dummy asset files\n with open(os.path.join(app.static_folder, 'js', 'main.js'), 'w') as f:\n f.write('console.log(\"Main JS loaded\");')\n with open(os.path.join(app.static_folder, 'js', 'utils.js'), 'w') as f:\n f.write('function utility() { return \"utility\"; }')\n with open(os.path.join(app.static_folder, 'css', 'style.css'), 'w') as f:\n f.write('body { font-family: sans-serif; }')\n with open(os.path.join(app.static_folder, 'css', 'theme.css'), 'w') as f:\n f.write('h1 { color: #333; }')\n\n # Create a simple template (templates/index.html)\n template_content = '''\n\n\n\n \n \n Flask-Assets Example\n {% assets \"main_css\" %}\n \n {% endassets %}\n\n\n

Hello from Flask-Assets!

\n {% assets \"main_js\" %}\n \n {% endassets %}\n\n\n '''\n os.makedirs('templates', exist_ok=True)\n with open('templates/index.html', 'w') as f:\n f.write(template_content)\n\n app.run(debug=True)","lang":"python","description":"This quickstart demonstrates how to set up `Flask-Assets` to manage CSS and JavaScript files. It initializes an `Environment`, defines `Bundle` objects for minifying and combining static files, registers them, and shows how to include these bundles in a Jinja2 template. Run the script, then navigate to `http://127.0.0.1:5000/` in your browser. The static files will be automatically generated in `static/gen`."},"warnings":[{"fix":"Upgrade your Flask application to Flask 2.2.x or newer: `pip install -U Flask`.","message":"Flask-Assets 2.1.0 (and newer versions) officially supports Flask 2.2.x and above. Older Flask versions (e.g., Flask 1.x) may experience compatibility issues or unexpected behavior.","severity":"breaking","affected_versions":"<2.1.0"},{"fix":"Install the required filter packages, e.g., `pip install jsmin cssmin lesscpy pyscss`.","message":"Filters specified in `Bundle` (e.g., 'jsmin', 'cssmin', 'less', 'sass') require their corresponding Python packages to be installed separately. Flask-Assets does not automatically install these filter dependencies.","severity":"gotcha","affected_versions":"All"},{"fix":"Migrate from `flask_assets.ManageAssets` to using `flask assets` commands, which are automatically registered when Flask-Assets is installed with Flask 0.11+.","message":"The Flask-Script integration (`flask_assets.ManageAssets`) is considered legacy. For command-line asset management, use the built-in Flask CLI integration (`flask assets` command) which is available for Flask 0.11+.","severity":"deprecated","affected_versions":"<0.12"},{"fix":"If using blueprints and custom asset paths, avoid setting `Environment.directory` or `Environment.load_path` globally, or manage blueprint-specific asset paths manually.","message":"Setting `Environment.directory` or `Environment.load_path` explicitly disables Flask-Assets' built-in blueprint static file resolution. All paths will then be considered relative to the specified custom directory/URL.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `Environment(app)` or `assets.init_app(app)` is called after creating your Flask app. If using an application factory, call `assets.init_app(app)` within the factory function after the app is created. The `Environment` constructor automatically registers the Jinja2 extension when an app instance is passed.","cause":"The Flask-Assets Jinja2 extension is not correctly registered or initialized with the Flask application.","error":"TemplateSyntaxError: Encountered unknown tag 'assets'"},{"fix":"Install the Python package that provides the missing filter. For 'jsmin', run `pip install jsmin`. For other filters, consult the `webassets` documentation for the correct package name (e.g., `cssmin`, `lesscpy`, `pyscss`).","cause":"A specified filter (e.g., `jsmin`, `cssmin`, `less`, `sass`) is not installed in the Python environment.","error":"webassets.exceptions.FilterError: Filter 'jsmin' not found"},{"fix":"Verify that `output` paths in your `Bundle` definitions are correct and relative to your Flask app's static directory. In development, ensure `ASSETS_DEBUG` is `True` to see individual files or set `app.config['ASSETS_AUTO_BUILD'] = True` (or manually run `flask assets build`) to ensure bundles are generated.","cause":"The generated asset file (e.g., `packed.js` or `packed.css`) is not found, often due to incorrect paths, `ASSETS_DEBUG` configuration, or the files not being built.","error":"GET /static/gen/packed.js HTTP/1.1\" 404 -"},{"fix":"Pass data from Flask to JavaScript by rendering a `